Create more documentation (#7627)

* Documentation, format class, no modification.

app/fax/fax_emails.php

@@ -40,6 +40,13 @@ $sql .= "and fax_email_outbound_subject_tag is not null ";
 $result = $database->select($sql, null, 'all');
 unset($sql);
 
+/**
+ * Converts an array to a map where each unique value in the array is mapped to true.
+ *
+ * @param array &$arr The input array
+ *
+ * @return array|false A map where each unique value in the array is mapped to true, or false if the input array is empty.
+ */
 function arr_to_map(&$arr){
 	if (!empty($arr)){
 		$map = Array();

app/fax/fax_send.php

@@ -127,6 +127,13 @@
 
 //define function correct_path
 if (!function_exists('correct_path')) {
+	/**
+	 * Corrects a file path to match the current operating system's conventions.
+	 *
+	 * @param string $p The file path to correct
+	 *
+	 * @return string The corrected file path
+	 */
 	function correct_path($p) {
 		global $IS_WINDOWS;
 		if ($IS_WINDOWS) {
@@ -138,6 +145,17 @@ if (!function_exists('correct_path')) {
 
 //define function gs_cmd
 if (!function_exists('gs_cmd')) {
+	/**
+	 * Generates a command to execute Ghostscript.
+	 *
+	 * The command is constructed based on the value of $IS_WINDOWS, which indicates
+	 * whether the script is running under Windows. If it is, the command includes
+	 * the 'gswin32c' executable, otherwise it uses 'gs'.
+	 *
+	 * @param string $args Command line arguments to be passed to Ghostscript.
+	 *
+	 * @return string The constructed command as a string.
+	 */
 	function gs_cmd($args) {
 		global $IS_WINDOWS;
 		if ($IS_WINDOWS) {
@@ -149,7 +167,17 @@ if (!function_exists('gs_cmd')) {
 
 //define function fax_split dtmf
 if (!function_exists('fax_split_dtmf')) {
-	function fax_split_dtmf(&$fax_number, &$fax_dtmf){
+	/**
+	 * Splits a fax number string into its numeric and DTMF (Dual-Tone Multi-Frequency) parts.
+	 *
+	 * If the input fax number is in the format '12345678 (DTMF_digits)', this function
+	 * extracts the numeric part and stores it in $fax_number, while storing the DTMF digits
+	 * in $fax_dtmf.
+	 *
+	 * @param string &$fax_number The fax number to be split. Modified to contain only the numeric part.
+	 * @param string &$fax_dtmf   The extracted DTMF digits from the input fax number.
+	 */
+	function fax_split_dtmf(&$fax_number, &$fax_dtmf) {
 		$tmp = array();
 		$fax_dtmf = '';
 		if (preg_match('/^\s*(.*?)\s*\((.*)\)\s*$/', $fax_number, $tmp)){

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)) {