Add some basic documentation, and remove some long-obsolete functions.

functions/imap_asearch.php

@@ -81,6 +81,7 @@ $imap_error_titles = array(
 	'BYE' => _("ERROR : Imap server closed the connection.")
 );
 
+// why can't this just use sqimap_error_box() ?
 function sqimap_asearch_error_box($response, $query, $message)
 {
 	global $imap_error_titles;
@@ -108,7 +109,9 @@ function sqimap_asearch_error_box($response, $query, $message)
 	}
 }
 
-/* This is to avoid the E_NOTICE warnings signaled by marc AT squirrelmail.org. Thanks Marc! */
+/**
+ * This is to avoid the E_NOTICE warnings signaled by marc AT squirrelmail.org. Thanks Marc!
+ */
 function asearch_nz(&$var)
 {
 	if (isset($var))
@@ -116,7 +119,10 @@ function asearch_nz(&$var)
 	return '';
 }
 
-/* This should give the same results as PHP 4 >= 4.3.0's html_entity_decode(), except it doesn't handle hex constructs */
+/**
+ * This should give the same results as PHP 4 >= 4.3.0's html_entity_decode(),
+ * except it doesn't handle hex constructs
+ */
 function asearch_unhtmlentities($string) {
 	$trans_tbl = array_flip(get_html_translation_table(HTML_ENTITIES));
 	for ($i=127; $i<255; $i++)	/* Add &#<dec>; entities */
@@ -160,11 +166,13 @@ function sqimap_asearch_encode_string($what, $charset)
 	return '"' . $what . '"';	// 4.3 quoted string form
 }
 
-/*
- Parses a user date string into an rfc2060 date string (<day number>-<US month TLA>-<4 digit year>)
- Returns a preg_match-style array: [0]: fully formatted date, [1]: day, [2]: month, [3]: year
- Handles space, slash, backslash, dot and comma as separators (and dash of course ;=)
-*/
+/**
+ * Parses a user date string into an rfc2060 date string
+ * (<day number>-<US month TLA>-<4 digit year>).
+ * Returns a preg_match-style array: [0]: fully formatted date,
+ * [1]: day, [2]: month, [3]: year
+ * Handles space, slash, backslash, dot and comma as separators (and dash of course ;=)
+ */
 function sqimap_asearch_parse_date($what)
 {
 	global $imap_asearch_months;

functions/imap_general.php

@@ -20,7 +20,12 @@ require_once(SM_PATH . 'functions/auth.php');
 global $sqimap_session_id;
 $sqimap_session_id = 1;
 
-/* Sets an unique session id in order to avoid simultanous sessions crash. */
+/**
+ * Generates a new session ID by incrementing the last one used;
+ * this ensures that each command has a unique ID.
+ * @param bool unique_id
+ * @return string IMAP session id of the form 'A000'.
+ */
 function sqimap_session_id($unique_id = false) {
     global $data_dir, $username, $sqimap_session_id;
     if (!$unique_id) {
@@ -30,7 +35,7 @@ function sqimap_session_id($unique_id = false) {
     }
 }
 
-/*
+/**
  * Both send a command and accept the result from the command.
  * This is to allow proper session number handling.
  */
@@ -88,6 +93,7 @@ function sqimap_run_command ($imap_stream, $query, $handle_errors, &$response,
         return false;
     }    
 }
+
 function sqimap_prepare_pipelined_query($new_query,&$tag,&$aQuery,$unique_id) {
     $sid = sqimap_session_id($unique_id);
     $tag_uid_a = explode(' ',trim($sid));
@@ -159,11 +165,12 @@ function sqimap_run_pipelined_command ($imap_stream, $aQueryList, $handle_errors
     return $aResults;
 }
 
-/* 
- * custom fgets function. gets a line from IMAP
- * no matter how big it may be
+/** 
+ * Custom fgets function: gets a line from the IMAP-server,
+ * no matter how big it may be.
+ * @param stream imap_stream the stream to read from
+ * @return string a line
  */
-
 function sqimap_fgets($imap_stream) {
     $read = '';
     $buffer = 4096;
@@ -245,7 +252,10 @@ function sqimap_fread($imap_stream,$iSize,$filter=false,
     return $results;       
 }        
 
-/* obsolete function, inform plugins that use it */
+/**
+ * Obsolete function, inform plugins that use it
+ * @deprecated use sqimap_run_command or sqimap_run_command_list instead
+ */
 function sqimap_read_data_list($imap_stream, $tag, $handle_errors, 
           &$response, &$message, $query = '') {
     global $color, $squirrelmail_language;
@@ -266,6 +276,14 @@ function sqimap_read_data_list($imap_stream, $tag, $handle_errors,
     exit; 
 }
 
+/**
+ * Function to display an error related to an IMAP-query.
+ * @param string title the caption of the error box
+ * @param string query the query that went wrong
+ * @param string message_title
+ * @param string message the error message
+ * @return void
+ */
 function sqimap_error_box($title, $query = '', $message_title = '', $message = '')
 {
     global $color, $squirrelmail_language;
@@ -286,12 +304,11 @@ function sqimap_error_box($title, $query = '', $message_title = '', $message = '
     error_box($string,$color);
 }
 
-/*
+/**
  * Reads the output from the IMAP stream.  If handle_errors is set to true,
  * this will also handle all errors that are received.  If it is not set,
- * the errors will be sent back through $response and $message
+ * the errors will be sent back through $response and $message.
  */
-
 function sqimap_retrieve_imap_response($imap_stream, $tag, $handle_errors, 
           &$response, &$message, $query = '',
            $filter = false, $outputstream = false, $no_return = false) {
@@ -529,10 +546,13 @@ function sqimap_read_data ($imap_stream, $tag_uid, $handle_errors,
     }
 }
 
-/** sqimap_create_stream()
- * @return imap-stream resource identifier
+/**
  * Connects to the IMAP server and returns a resource identifier for use with
  * the other SquirrelMail IMAP functions.  Does NOT login!
+ * @param string server hostname of IMAP server
+ * @param int port port number to connect to
+ * @param bool tls whether to use TLS when connecting.
+ * @return imap-stream resource identifier
  */
 function sqimap_create_stream($server,$port,$tls=false) {
     global $username, $use_imap_tls;
@@ -566,7 +586,7 @@ function sqimap_create_stream($server,$port,$tls=false) {
     return $imap_stream;
 }
 
-/*
+/**
  * Logs the user into the imap server.  If $hide is set, no error messages
  * will be displayed.  This function returns the imap connection handle.
  */
@@ -718,7 +738,11 @@ function sqimap_login ($username, $password, $imap_server_address, $imap_port, $
     return $imap_stream;
 }
 
-/* Simply logs out the IMAP session */
+/**
+ * Simply logs out the IMAP session
+ * @param stream imap_stream the IMAP connection to log out.
+ * @return void
+ */
 function sqimap_logout ($imap_stream) {
     /* Logout is not valid until the server returns 'BYE'
      * If we don't have an imap_ stream we're already logged out */
@@ -726,6 +750,11 @@ function sqimap_logout ($imap_stream) {
         sqimap_run_command($imap_stream, 'LOGOUT', false, $response, $message);
 }
 
+/**
+ * Retreive the CAPABILITY string from the IMAP server.
+ * If capability is set, returns only that specific capability,
+ * else returns array of all capabilities.
+ */
 function sqimap_capability($imap_stream, $capability='') {
     global $sqimap_capabilities;
     if (!is_array($sqimap_capabilities)) {
@@ -751,7 +780,9 @@ function sqimap_capability($imap_stream, $capability='') {
     return $sqimap_capabilities;
 }
 
-/* Returns the delimeter between mailboxes: INBOX/Test, or INBOX.Test */
+/**
+ * Returns the delimeter between mailboxes: INBOX/Test, or INBOX.Test
+ */
 function sqimap_get_delimiter ($imap_stream = false) {
     global $sqimap_delimiter, $optional_delimiter;
 
@@ -797,7 +828,11 @@ function sqimap_get_delimiter ($imap_stream = false) {
     return $sqimap_delimiter;
 }
 
-
+/**
+ * This encodes a mailbox name for use in IMAP commands.
+ * @param string what the mailbox to encode
+ * @return string the encoded mailbox string
+ */
 function sqimap_encode_mailbox_name($what)
 {
 	if (ereg("[\"\\\r\n]", $what))
@@ -806,7 +841,9 @@ function sqimap_encode_mailbox_name($what)
 }
 
 
-/* Gets the number of messages in the current mailbox. */
+/**
+ * Gets the number of messages in the current mailbox.
+ */
 function sqimap_get_num_messages ($imap_stream, $mailbox) {
     $read_ary = sqimap_run_command ($imap_stream, 'EXAMINE ' . sqimap_encode_mailbox_name($mailbox), false, $result, $message);
     for ($i = 0; $i < count($read_ary); $i++) {
@@ -817,7 +854,6 @@ function sqimap_get_num_messages ($imap_stream, $mailbox) {
     return false; //"BUG! Couldn't get number of messages in $mailbox!";
 }
 
-
 function parseAddress($address, $max=0) {
     $aTokens = array();
     $aAddress = array();
@@ -988,9 +1024,8 @@ function parseAddress($address, $max=0) {
 } 
 
 
-
-/*
- * Returns the number of unseen messages in this folder
+/**
+ * Returns the number of unseen messages in this folder.
  */
 function sqimap_unseen_messages ($imap_stream, $mailbox) {
     $read_ary = sqimap_run_command ($imap_stream, 'STATUS ' . sqimap_encode_mailbox_name($mailbox) . ' (UNSEEN)', false, $result, $message);
@@ -1005,7 +1040,7 @@ function sqimap_unseen_messages ($imap_stream, $mailbox) {
     return $regs[1];
 }
 
-/*
+/**
  * Returns the number of total/unseen/recent messages in this folder
  */
 function sqimap_status_messages ($imap_stream, $mailbox) {
@@ -1029,8 +1064,8 @@ function sqimap_status_messages ($imap_stream, $mailbox) {
 }
 
 
-/*
- *  Saves a message to a given folder -- used for saving sent messages
+/**
+ * Saves a message to a given folder -- used for saving sent messages
  */
 function sqimap_append ($imap_stream, $sent_folder, $length) {
     fputs ($imap_stream, sqimap_session_id() . ' APPEND ' . sqimap_encode_mailbox_name($sent_folder) . " (\\Seen) \{$length}\r\n");
@@ -1078,11 +1113,12 @@ function sqimap_get_user_server ($imap_server, $username) {
    return $function($username);
 }
 
-/* This is an example that gets imapservers from yellowpages (NIS).
+/**
+ * This is an example that gets imapservers from yellowpages (NIS).
  * you can simple put map:map_yp_alias in your $imap_server_address 
  * in config.php use your own function instead map_yp_alias to map your
- * LDAP whatever way to find the users imapserver. */
-
+ * LDAP whatever way to find the users imapserver.
+ */
 function map_yp_alias($username) {
    $yp = `ypmatch $username aliases`;
    return chop(substr($yp, strlen($username)+1));

functions/imap_mailbox.php

@@ -85,7 +85,7 @@ function sortSpecialMbx($a, $b) {
     } else {
         $bcmp = '2' . $b->mailboxname_full;
     }
-    return user_strcasecmp($acmp, $bcmp);	
+    return strnatcasecmp($acmp, $bcmp);	
 }
 
 function compact_mailboxes_response($ary)
@@ -108,20 +108,11 @@ function compact_mailboxes_response($ary)
     return array_values(array_unique($ary));
 }
 
-/*
-function find_mailbox_name ($mailbox) {
-    if (preg_match('/\*.+\"([^\r\n\"]*)\"[\s\r\n]*$/', $mailbox, $regs)) 
-        return $regs[1];
-    if (ereg(" *\"([^\r\n\"]*)\"[ \r\n]*$", $mailbox, $regs))
-        return $regs[1];
-    ereg(" *([^ \r\n\"]*)[ \r\n]*$",$mailbox,$regs);
-    return $regs[1];
-}
-*/
-
-// Extract the mailbox name from an untagged LIST (7.2.2) or LSUB (7.2.3) answer
-// * (LIST|LSUB) (<Flags list>) (NIL|"<separator atom>") <mailbox name string>\r\n
-// mailbox name in quoted string MUST be unquoted and stripslashed (sm API)
+/**
+ * Extract the mailbox name from an untagged LIST (7.2.2) or LSUB (7.2.3) answer
+ * (LIST|LSUB) (<Flags list>) (NIL|"<separator atom>") <mailbox name string>\r\n
+ * mailbox name in quoted string MUST be unquoted and stripslashed (sm API)
+ */
 function find_mailbox_name($line)
 {
     if (preg_match('/^\* (?:LIST|LSUB) \([^\)]*\) (?:NIL|\"[^\"]*\") ([^\r\n]*)[\r\n]*$/i', $line, $regs)) {
@@ -132,10 +123,16 @@ function find_mailbox_name($line)
     return '';
 }
 
+/**
+ * @return bool whether this is a Noselect mailbox.
+ */
 function check_is_noselect ($lsub_line) {
     return preg_match("/^\* (LSUB|LIST) \([^\)]*\\\\Noselect[^\)]*\)/i", $lsub_line);
 }
 
+/**
+ * @return bool whether this is a Noinferiors mailbox.
+ */
 function check_is_noinferiors ($lsub_line) {
     return preg_match("/^\* (LSUB|LIST) \([^\)]*\\\\Noinferiors[^\)]*\)/i", $lsub_line);
 }
@@ -182,7 +179,10 @@ function isBoxBelow( $subbox, $parentbox ) {
         }
 }
 
-/* Defines special mailboxes */
+/**
+ * Defines special mailboxes: given a mailbox name, it checks if this is a
+ * "special" one: INBOX, Trash, Sent or Draft.
+ */
 function isSpecialMailbox( $box ) {
     $ret = ( (strtolower($box) == 'inbox') ||
              isTrashMailbox($box) || isSentMailbox($box) || isDraftMailbox($box) );
@@ -193,25 +193,36 @@ function isSpecialMailbox( $box ) {
     return $ret;
 }
 
+/**
+ * @return bool whether this is a Trash folder
+ */
 function isTrashMailbox ($box) {
     global $trash_folder, $move_to_trash;
     return $move_to_trash && $trash_folder &&
            ( $box == $trash_folder || isBoxBelow($box, $trash_folder) );
 }
 
+/**
+ * @return bool whether this is a Sent folder
+ */
 function isSentMailbox($box) {
    global $sent_folder, $move_to_sent;
    return $move_to_sent && $sent_folder &&
           ( $box == $sent_folder || isBoxBelow($box, $sent_folder) );
 }
 
+/**
+ * @return bool whether this is a Draft folder
+ */
 function isDraftMailbox($box) {
    global $draft_folder, $save_as_draft;
    return $save_as_draft &&
           ( $box == $draft_folder || isBoxBelow($box, $draft_folder) );
 }
 
-/* Expunges a mailbox */
+/**
+ * Expunges a mailbox, ie. delete all contents.
+ */
 function sqimap_mailbox_expunge ($imap_stream, $mailbox, $handle_errors = true, $id='') {
     global $uid_support;
     if ($id) {
@@ -237,7 +248,9 @@ function sqimap_mailbox_expunge ($imap_stream, $mailbox, $handle_errors = true,
     return $cnt;
 }
 
-/* Checks whether or not the specified mailbox exists */
+/**
+ * Checks whether or not the specified mailbox exists
+ */
 function sqimap_mailbox_exists ($imap_stream, $mailbox) {
     if (!isset($mailbox) || empty($mailbox)) {
         return false;
@@ -247,7 +260,9 @@ function sqimap_mailbox_exists ($imap_stream, $mailbox) {
     return isset($mbx[0]);
 }
 
-/* Selects a mailbox */
+/**
+ * Selects a mailbox
+ */
 function sqimap_mailbox_select ($imap_stream, $mailbox) {
     global $auto_expunge;
 
@@ -283,41 +298,55 @@ function sqimap_mailbox_select ($imap_stream, $mailbox) {
     return $result;
 }
 
-/* Creates a folder */
+/**
+ * Creates a folder.
+ */
 function sqimap_mailbox_create ($imap_stream, $mailbox, $type) {
     global $delimiter;
     if (strtolower($type) == 'noselect') {
         $mailbox .= $delimiter;
     }
 
-    $read_ary = sqimap_run_command($imap_stream, 'CREATE ' . sqimap_encode_mailbox_name($mailbox),
+    $read_ary = sqimap_run_command($imap_stream, 'CREATE ' .
+                                   sqimap_encode_mailbox_name($mailbox),
                                    true, $response, $message);
     sqimap_subscribe ($imap_stream, $mailbox);
 }
 
-/* Subscribes to an existing folder */
+/**
+ * Subscribes to an existing folder.
+ */
 function sqimap_subscribe ($imap_stream, $mailbox) {
-    $read_ary = sqimap_run_command($imap_stream, 'SUBSCRIBE ' . sqimap_encode_mailbox_name($mailbox),
+    $read_ary = sqimap_run_command($imap_stream, 'SUBSCRIBE ' .
+                                   sqimap_encode_mailbox_name($mailbox),
                                    true, $response, $message);
 }
 
-/* Unsubscribes to an existing folder */
+/**
+ * Unsubscribes from an existing folder
+ */
 function sqimap_unsubscribe ($imap_stream, $mailbox) {
-    $read_ary = sqimap_run_command($imap_stream, 'UNSUBSCRIBE ' . sqimap_encode_mailbox_name($mailbox),
+    $read_ary = sqimap_run_command($imap_stream, 'UNSUBSCRIBE ' .
+                                   sqimap_encode_mailbox_name($mailbox),
                                    true, $response, $message);
 }
 
-/* Deletes the given folder */
+/**
+ * Deletes the given folder
+ */
 function sqimap_mailbox_delete ($imap_stream, $mailbox) {
     global $data_dir, $username;
-    $read_ary = sqimap_run_command($imap_stream, 'DELETE ' . sqimap_encode_mailbox_name($mailbox),
+    $read_ary = sqimap_run_command($imap_stream, 'DELETE ' .
+                                   sqimap_encode_mailbox_name($mailbox),
                                    true, $response, $message);
     sqimap_unsubscribe ($imap_stream, $mailbox);
     do_hook_function('rename_or_delete_folder', $args = array($mailbox, 'delete', ''));
     removePref($data_dir, $username, "thread_$mailbox");
 }
 
-/* Determines if the user is subscribed to the folder or not */
+/**
+ * Determines if the user is subscribed to the folder or not
+ */
 function sqimap_mailbox_is_subscribed($imap_stream, $folder) {
     $boxesall = sqimap_mailbox_list ($imap_stream);
     foreach ($boxesall as $ref) {
@@ -328,7 +357,9 @@ function sqimap_mailbox_is_subscribed($imap_stream, $folder) {
     return false;
 }
 
-/* Renames a mailbox */
+/**
+ * Renames a mailbox.
+ */
 function sqimap_mailbox_rename( $imap_stream, $old_name, $new_name ) {
     if ( $old_name != $new_name ) {
         global $delimiter, $imap_server_type, $data_dir, $username;
@@ -341,7 +372,8 @@ function sqimap_mailbox_rename( $imap_stream, $old_name, $new_name ) {
         }
 
         $boxesall = sqimap_mailbox_list($imap_stream);
-        $cmd = 'RENAME ' . sqimap_encode_mailbox_name($old_name) . ' ' . sqimap_encode_mailbox_name($new_name);
+        $cmd = 'RENAME ' . sqimap_encode_mailbox_name($old_name) .
+	             ' ' . sqimap_encode_mailbox_name($new_name);
         $data = sqimap_run_command($imap_stream, $cmd, true, $response, $message);
         sqimap_unsubscribe($imap_stream, $old_name.$postfix);
         $oldpref = getPref($data_dir, $username, 'thread_'.$old_name.$postfix);
@@ -372,7 +404,7 @@ function sqimap_mailbox_rename( $imap_stream, $old_name, $new_name ) {
     }
 }
 
-/*
+/**
  * Formats a mailbox into parts for the $boxesall array
  *
  * The parts are:
@@ -447,23 +479,7 @@ function sqimap_mailbox_parse ($line, $line_lsub) {
     return $boxesall;
 }
 
-/*
- * Sorting function used to sort mailbox names.
- *     + Original patch from dave_michmerhuizen@yahoo.com
- *     + Allows case insensitivity when sorting folders
- *     + Takes care of the delimiter being sorted to the end, causing
- *       subfolders to be listed in below folders that are prefixed
- *       with their parent folders name.
- *
- *       For example: INBOX.foo, INBOX.foobar, and INBOX.foo.bar
- *       Without special sort function: foobar between foo and foo.bar
- *       With special sort function: foobar AFTER foo and foo.bar :)
- */
-function user_strcasecmp($a, $b) {
-    return  strnatcasecmp($a, $b);
-}
-
-/*
+/**
  * Returns list of options (to be echoed into select statement
  * based on available mailboxes and separators
  * Caller should surround options with <SELECT..> </SELECT> and
@@ -532,7 +548,7 @@ function sqimap_mailbox_option_list($imap_stream, $show_selected = 0, $folder_sk
     return $mbox_options;
 }
 
-/*
+/**
  * Returns sorted mailbox lists in several different ways. 
  * See comment on sqimap_mailbox_parse() for info about the returned array.
  */
@@ -571,7 +587,7 @@ function sqimap_mailbox_list($imap_stream) {
 
         /* natural sort mailboxes */
         if (isset($sorted_lsub_ary)) {
-            usort($sorted_lsub_ary, 'user_strcasecmp');
+            usort($sorted_lsub_ary, 'strnatcasecmp');
         }
         /*
          * The LSUB response doesn't provide us information about \Noselect
@@ -645,7 +661,7 @@ function sqimap_mailbox_list($imap_stream) {
     return $boxesnew;
 }
 
-/*
+/**
  *  Returns a list of all folders, subscribed or not
  */
 function sqimap_mailbox_list_all($imap_stream) {
@@ -930,22 +946,6 @@ function sqimap_tree_to_ref_array(&$mbx_tree,&$aMbxs) {
    }
 } 
 
-
-/* Define preferences for folder settings. */
-/* FIXME, we should load constants.php
-unseen_notify
-define('SMPREF_UNSEEN_NONE', 1);
-define('SMPREF_UNSEEN_INBOX', 2);
-define('SMPREF_UNSEEN_ALL', 3);
-
-define('SMPREF_UNSEEN_SPECIAL', 4); // Only special folders
-define('SMPREF_UNSEEN_NORMAL', 5);  // Only normal folders
-
-unseen_type
-define('SMPREF_UNSEEN_ONLY', 1);
-define('SMPREF_UNSEEN_TOTAL', 2);
-*/
-
 function sqimap_get_status_mbx_tree($imap_stream,&$mbx_tree) {
     global $unseen_notify, $unseen_type, $trash_folder,$move_to_trash;
     $aMbxs = $aQuery = $aTag = array();

functions/imap_messages.php

@@ -90,12 +90,6 @@ function sqimap_messages_flag ($imap_stream, $start, $end, $flag, $handle_errors
     $read = sqimap_run_command ($imap_stream, "STORE $start:$end +FLAGS (\\$flag)", $handle_errors, $response, $message, $uid_support);
 }
 
-/* Remove specified flag from specified messages */
-function sqimap_messages_remove_flag ($imap_stream, $start, $end, $flag, $handle_errors) {
-    global $uid_support;
-    $read = sqimap_run_command ($imap_stream, "STORE $start:$end -FLAGS (\\$flag)", $handle_errors, $response, $message, $uid_support);
-}
-
 function sqimap_toggle_flag($imap_stream, $id, $flag, $set, $handle_errors) {
     global $uid_support;
     $msgs_id = sqimap_message_list_squisher($id);
@@ -103,13 +97,13 @@ function sqimap_toggle_flag($imap_stream, $id, $flag, $set, $handle_errors) {
     $read = sqimap_run_command ($imap_stream, "STORE $msgs_id ".$set_string."FLAGS ($flag)", $handle_errors, $response, $message, $uid_support);
 }
 
-// obsolete?
+/** @deprecated */
 function sqimap_get_small_header ($imap_stream, $id, $sent) {
     $res = sqimap_get_small_header_list($imap_stream, $id, $sent);
     return $res[0];
 }
 
-/*
+/**
  * Sort the message list and crunch to be as small as possible
  * (overflow could happen, so make it small if possible)
  */
@@ -137,25 +131,9 @@ function sqimap_message_list_squisher($messages_array) {
     return $msgs_str;
 }
 
-/* returns the references header lines */
-function get_reference_header ($imap_stream, $message) {
-    global $uid_support;
-    $responses = array ();
-    $results = array();
-    $references = "";
-    $responses = sqimap_run_command_list ($imap_stream, "FETCH $message BODY[HEADER.FIELDS (References)]", true, $response, $message, $uid_support);
-    if (!eregi("^\\* ([0-9]+) FETCH", $responses[0][0], $regs)) {
-        $responses = array ();
-    } 
-    return $responses;
-}
-
-
-/* get sort order from server and
- * return it as the $id array for
- * mailbox_display
+/**
+ * Get sort order from server and return it as the $id array for mailbox_display.
  */
-
 function sqimap_get_sort_order ($imap_stream, $sort, $mbxresponse) {
     global  $default_charset, $thread_sort_messages,
             $internal_date_sort, $server_sort_array,
@@ -268,16 +246,16 @@ function sqimap_get_php_sort_order ($imap_stream, $mbxresponse) {
 }
 
 
-/* returns an indent array for printMessageinfo()
-   this represents the amount of indent needed (value)
-   for this message number (key)
-*/
-
+/**
+ * Returns an indent array for printMessageinfo()
+ * This represents the amount of indent needed (value),
+ * for this message number (key)
+ */
 function get_parent_level ($imap_stream) {
     global $sort_by_ref, $default_charset, $thread_new;
-        $parent = "";
-        $child = "";
-        $cutoff = 0;
+    $parent = '';
+    $child  = '';
+    $cutoff = 0;
 
     /* loop through the threads and take unwanted characters out 
        of the thread string then chop it up 
@@ -367,11 +345,10 @@ function get_parent_level ($imap_stream) {
 }
 
 
-/* returns an array with each element as a string
-   representing one message thread as returned by
-   the IMAP server
-*/
-
+/**
+ * Returns an array with each element as a string representing one
+ * message-thread as returned by the IMAP server.
+ */
 function get_thread_sort ($imap_stream) {
     global $thread_new, $sort_by_ref, $default_charset, $server_sort_array, $uid_support;
     if (sqsession_is_registered('thread_new')) {
@@ -735,62 +712,7 @@ function sqimap_get_small_header_list ($imap_stream, $msg_list, $show_num=false)
     return $new_messages;
 }
 
-// obsolete?
-function sqimap_get_headerfield($imap_stream, $field) {
-    global $uid_support;
-    $sid = sqimap_session_id(false);
-
-    $results = array();
-    $read_list = array();
-
-    $query = "FETCH 1:* (UID BODY.PEEK[HEADER.FIELDS ($field)])";
-    $readin_list = sqimap_run_command_list ($imap_stream, $query, true, $response, $message, $uid_support);
-    $i = 0;
-
-    foreach ($readin_list as $r) {
-        $r = implode('',$r);
-        /* first we unfold the header */
-        $r = str_replace(array("\r\n\t","\r\n\s"),array('',''),$r);
-        /* 
-         * now we can make a new header array with each element representing 
-         * a headerline
-         */
-        $r = explode("\r\n" , $r);  
-        if (!$uid_support) {
-            if (!preg_match("/^\\*\s+([0-9]+)\s+FETCH/iAU",$r[0], $regs)) {
-                set_up_language($squirrelmail_language);
-                echo '<br><b><font color=$color[2]>' .
-                      _("ERROR : Could not complete request.") .
-                      '</b><br>' .
-                      _("Unknown response from IMAP server: ") . ' 1.' .
-                      $r[0] . "</font><br>\n";
-            } else {
-                $id = $regs[1];
-            }
-        } else {
-            if (!preg_match("/^\\*\s+([0-9]+)\s+FETCH.*UID\s+([0-9]+)\s+/iAU",$r[0], $regs)) {
-                set_up_language($squirrelmail_language);
-                echo '<br><b><font color=$color[2]>' .
-                     _("ERROR : Could not complete request.") .
-                     '</b><br>' .
-                     _("Unknown response from IMAP server: ") . ' 1.' .
-                     $r[0] . "</font><br>\n";
-            } else {
-                $id = $regs[2];
-            }
-        }
-        $field = $r[1];
-        $field = substr($field,strlen($field)+2);
-        $result[] = array($id,$field);
-    }
-    return $result;
-}
-
-
-
-
- 
-/*
+/**
  * Returns a message array with all the information about a message.  
  * See the documentation folder for more information about this array.
  */
@@ -824,37 +746,4 @@ function sqimap_get_message ($imap_stream, $id, $mailbox) {
     return $msg;
 }
 
-/* Wrapper function that reformats the header information. */
-// obsolete?
-function sqimap_get_message_header ($imap_stream, $id, $mailbox) {
-    global $uid_support;
-    $read = sqimap_run_command ($imap_stream, "FETCH $id BODY[HEADER]", true, $response, $message, $uid_support);
-    $header = sqimap_get_header($imap_stream, $read); 
-    $header->id = $id;
-    $header->mailbox = $mailbox;
-    return $header;
-}
-
-/* Wrapper function that reformats the entity header information. */
-// obsolete?
-function sqimap_get_ent_header ($imap_stream, $id, $mailbox, $ent) {
-    global $uid_support;
-    $read = sqimap_run_command ($imap_stream, "FETCH $id BODY[$ent.HEADER]", true, $response, $message, $uid_support);
-    $header = sqimap_get_header($imap_stream, $read); 
-    $header->id = $id;
-    $header->mailbox = $mailbox;
-    return $header;
-}
-
-/* function to get the mime headers */
-// obsolete?
-function sqimap_get_mime_ent_header ($imap_stream, $id, $mailbox, $ent) {
-    global $uid_support;
-    $read = sqimap_run_command ($imap_stream, "FETCH $id:$id BODY[$ent.MIME]", true, $response, $message, $uid_support);
-    $header = sqimap_get_header($imap_stream, $read); 
-    $header->id = $id;
-    $header->mailbox = $mailbox;
-    return $header;
-}
-
 ?>

include/options/display.php

@@ -17,7 +17,19 @@ define('SMOPT_GRP_GENERAL', 0);
 define('SMOPT_GRP_MAILBOX', 1);
 define('SMOPT_GRP_MESSAGE', 2);
 
-/* Define the optpage load function for the display options page. */
+/**
+ * This function builds an array with all the information about
+ * the options available to the user, and returns it. The options
+ * are grouped by the groups in which they are displayed.
+ * For each option, the following information is stored:
+ * - name: the internal (variable) name
+ * - caption: the description of the option in the UI
+ * - type: one of SMOPT_TYPE_*
+ * - refresh: one of SMOPT_REFRESH_*
+ * - size: one of SMOPT_SIZE_*
+ * - save: the name of a function to call when saving this option
+ * @return array all option information
+ */
 function load_optpage_data_display() {
     global $theme, $language, $languages, $js_autodetect_results,
     $compose_new_win, $default_use_mdn, $squirrelmail_language, $allow_thread_sort,
@@ -381,6 +393,10 @@ function load_optpage_data_display() {
 /** Define any specialized save functions for this option page. ***/
 /******************************************************************/
 
+/**
+ * This function saves a new theme setting.
+ * It updates the theme array.
+ */
 function save_option_theme($option) {
     global $theme;
 
@@ -401,6 +417,9 @@ function save_option_theme($option) {
     save_option($option);
 }
 
+/**
+ * This function saves the javascript detection option.
+ */
 function save_option_javascript_autodetect($option) {
     global $data_dir, $username, $new_javascript_setting;
 

include/options/folder.php

@@ -21,7 +21,19 @@ define('SMOPT_GRP_SPCFOLDER', 0);
 define('SMOPT_GRP_FOLDERLIST', 1);
 define('SMOPT_GRP_FOLDERSELECT', 2);
 
-/* Define the optpage load function for the folder options page. */
+/**
+ * This function builds an array with all the information about
+ * the options available to the user, and returns it. The options
+ * are grouped by the groups in which they are displayed.
+ * For each option, the following information is stored:
+ * - name: the internal (variable) name
+ * - caption: the description of the option in the UI
+ * - type: one of SMOPT_TYPE_*
+ * - refresh: one of SMOPT_REFRESH_*
+ * - size: one of SMOPT_SIZE_*
+ * - save: the name of a function to call when saving this option
+ * @return array all option information
+ */
 function load_optpage_data_folder() {
     global $username, $key, $imapServerAddress, $imapPort;
     global $folder_prefix, $default_folder_prefix, $show_prefix_option;
@@ -232,6 +244,10 @@ function load_optpage_data_folder() {
 /******************************************************************/
 /** Define any specialized save functions for this option page. ***/
 /******************************************************************/
+
+/**
+ * Saves the trash folder option.
+ */
 function save_option_trash_folder($option) {
     global $data_dir, $username;
 
@@ -243,6 +259,9 @@ function save_option_trash_folder($option) {
     save_option($option);
 }
 
+/**
+ * Saves the sent folder option.
+ */
 function save_option_sent_folder($option) {
     global $data_dir, $username;
 
@@ -254,6 +273,9 @@ function save_option_sent_folder($option) {
     save_option($option);
 }
 
+/**
+ * Saves the draft folder option.
+ */
 function save_option_draft_folder($option) {
     global $data_dir, $username;
 

include/options/personal.php

@@ -21,7 +21,19 @@ define('SMOPT_GRP_REPLY', 1);
 define('SMOPT_GRP_SIG', 2);
 define('SMOPT_GRP_TZ', 3);
 
-/* Define the optpage load function for the personal options page. */
+/**
+ * This function builds an array with all the information about
+ * the options available to the user, and returns it. The options
+ * are grouped by the groups in which they are displayed.
+ * For each option, the following information is stored:
+ * - name: the internal (variable) name
+ * - caption: the description of the option in the UI
+ * - type: one of SMOPT_TYPE_*
+ * - refresh: one of SMOPT_REFRESH_*
+ * - size: one of SMOPT_SIZE_*
+ * - save: the name of a function to call when saving this option
+ * @return array all option information
+ */
 function load_optpage_data_personal() {
     global $data_dir, $username, $edit_identity, $edit_name,
            $full_name, $reply_to, $email_address, $signature, $tzChangeAllowed,
@@ -211,6 +223,9 @@ function load_optpage_data_personal() {
 /** Define any specialized save functions for this option page. ***/
 /******************************************************************/
 
+/**
+ * Saves the signature option.
+ */
 function save_option_signature($option) {
     global $data_dir, $username;
     setSig($data_dir, $username, 'g', $option->new_value);