Create more documentation (#7627)

* Documentation, format class, no modification.

app/fax/resources/functions/object_to_array.php

@@ -1,5 +1,12 @@
 <?php
 
+/**
+ * Recursively converts an object or array to a multi-dimensional array.
+ *
+ * @param mixed $obj The object or array to be converted. If the value is neither an object nor an array, it will be returned as is.
+ *
+ * @return array A multi-dimensional array representation of the input object or array.
+ */
 function object_to_array($obj) {
 	if (!is_object($obj) && !is_array($obj)) { return $obj; }
 	if (is_object($obj)) { $obj = get_object_vars($obj); }

app/fax/resources/functions/parse_attachments.php

@@ -1,5 +1,16 @@
 <?php
 
+/**
+ * Parse attachments from a given email message.
+ *
+ * @param imap connection object $connection The IMAP connection to use for fetching the email message.
+ * @param int    $message_number The number of the email message to parse attachments from.
+ * @param string $option         Optional flag to pass to the imap_fetchstructure function.
+ *
+ * @return array An array of attachment details, where each element is an associative array containing
+ *               'filename', 'name', and 'attachment' keys. The return value will be a reindexed array,
+ *               with keys starting from 0.
+ */
 function parse_attachments($connection, $message_number, $option = '') {
 	$attachments = array();
 	$structure = imap_fetchstructure($connection, $message_number, $option);

app/fax/resources/functions/parse_message.php

@@ -1,5 +1,15 @@
 <?php
 
+/**
+ * Parse a message from the email connection.
+ *
+ * @param resource    $connection     IMAP connection to the mailbox
+ * @param int         $message_number The message number of the message to parse
+ * @param string|null $option         Optional argument for imap_fetchstructure()
+ * @param string      $to_charset     Charset to decode messages into, default is 'UTF-8'
+ *
+ * @return array An array containing two keys: 'messages' and 'attachments'. Each key contains an array of parsed messages or attachments.
+ */
 function parse_message($connection, $message_number, $option = null, $to_charset = 'UTF-8') {
 	$result = Array('messages'=>Array(),'attachments'=>Array());
 	$structure = imap_fetchstructure($connection, $message_number, $option);
@@ -33,6 +43,18 @@ function parse_message($connection, $message_number, $option = null, $to_charset
 	return $result;
 }
 
+/**
+ * Decode the text part of a message from the email connection.
+ *
+ * @param resource     $connection     IMAP connection to the mailbox
+ * @param array       &$part           The text part of the message, retrieved using imap_fetchstructure()
+ * @param int          $message_number The message number of the message to parse
+ * @param int          $id             Unique identifier for this part of the message
+ * @param string|null  $option         Optional argument for imap_fetchbody()
+ * @param string       $to_charset     Charset to decode messages into, default is 'UTF-8'
+ *
+ * @return array An array containing three keys: 'data', 'type', and 'size'. The 'data' key contains the decoded message text.
+ */
 function parse_message_decode_text($connection, &$part, $message_number, $id, $option, $to_charset){
 	$msg = parse_message_fetch_body($connection, $part, $message_number, $id, $option);
 
@@ -63,6 +85,17 @@ function parse_message_decode_text($connection, &$part, $message_number, $id, $o
 	);
 }
 
+/**
+ * Parse an attachment from the email connection.
+ *
+ * @param resource     $connection     IMAP connection to the mailbox
+ * @param object      &$part           The email part to parse
+ * @param int          $message_number The message number of the message containing the attachment
+ * @param string       $id             The internal ID of the attachment in the message
+ * @param string|null  $option         Optional argument for imap_fetchbody()
+ *
+ * @return array|false An array containing information about the parsed attachment, or false if no valid filename is found.
+ */
 function parse_message_decode_attach($connection, &$part, $message_number, $id, $option){
 	$filename = false;
 
@@ -99,6 +132,17 @@ function parse_message_decode_attach($connection, &$part, $message_number, $id,
 	);
 }
 
+/**
+ * Retrieves and decodes the body of a message from an email server.
+ *
+ * @param resource $connection     IMAP connection to the email server
+ * @param object & $part           Part of the email being processed
+ * @param int      $message_number The number of the message to retrieve
+ * @param string   $id             Unique identifier for the part
+ * @param int      $option         Option flag (default value is not documented)
+ *
+ * @return string The decoded body of the message
+ */
 function parse_message_fetch_body($connection, &$part, $message_number, $id, $option){
 	$body = imap_fetchbody($connection, $message_number, $id, $option);
 	if($part->encoding == ENCBASE64){
@@ -110,6 +154,13 @@ function parse_message_fetch_body($connection, &$part, $message_number, $id, $op
 	return $body;
 }
 
+/**
+ * Returns the type and subtype of a message part.
+ *
+ * @param object $part Message part object containing type and subtype information.
+ *
+ * @return string Type and subtype of the message part, separated by a slash. (e.g., "message/plain")
+ */
 function parse_message_get_type(&$part){
 	$types = Array(
 		TYPEMESSAGE     => 'message',
@@ -126,6 +177,17 @@ function parse_message_get_type(&$part){
 	return $types[$part->type] . '/' . strtolower($part->subtype);
 }
 
+/**
+ * Recursively flattens a hierarchical message structure into a single-level array.
+ *
+ * @param object $structure  Message structure containing nested parts and subparts.
+ * @param array &$result     Resulting flattened array of message parts.
+ * @param string $prefix     Prefix for each part in the result array (optional).
+ * @param int    $index      Index of the current part (used for generating prefixes, optional).
+ * @param bool   $fullPrefix Whether to include the index in the prefix or not (optional).
+ *
+ * @return array Flattened message structure.
+ */
 function parse_message_flatten(&$structure, &$result = array(), $prefix = '', $index = 1, $fullPrefix = true) {
 	foreach ($structure as $part) {
 		if(isset($part->parts)) {