Preparation to begin using phpdocumentor.

Added basic @package/@subpackage tags
The decode/ files were documented slightly more thoroughly, although they're almost self-explanatory anyway.

The individual functions in the functions/ files need to be documented though, and now that this commit is in, anyone willing to write docblocks for functions should get cracking ;)

functions/abook_database.php

@@ -28,10 +28,16 @@
  *        "AddressBook" class instead.
  *
  * $Id$
+ * @package squirrelmail
  */
-   
+
+/** Needs the DB functions */   
 require_once('DB.php');
-   
+
+/**
+ * Undocumented class - stores the addressbook in a sql database
+ * @package squirrelmail
+ */
 class abook_database extends addressbook_backend {
     var $btype = 'local';
     var $bname = 'database';

functions/abook_global_file.php

@@ -1,7 +1,7 @@
 <?php
 
 /**
- * abook_local_file.php
+ * abook_global_file.php
  *
  * Copyright (c) 1999-2003 The SquirrelMail Project Team
  * Licensed under the GNU GPL. For full terms see the file COPYING.
@@ -17,8 +17,13 @@
  * Make sure you configure this before using it!
  *
  * $Id$
+ * @package squirrelmail
  */
 
+/**
+ * Undocumented class - fixme
+ * @package squirrelmail
+ */
 class abook_global_file extends addressbook_backend {
     var $btype = 'local';
     var $bname = 'global_file';

functions/abook_ldap_server.php

@@ -25,8 +25,13 @@
  *       "AddressBook" class instead.
  *
  * $Id$
+ * @package squirrelmail
  */
 
+/**
+ * Undocumented class - fixme
+ * @package squirrelmail
+ */
 class abook_ldap_server extends addressbook_backend {
     var $btype = 'remote';
     var $bname = 'ldap_server';

functions/abook_local_file.php

@@ -19,8 +19,12 @@
  *       "AddressBook" class instead.
  *
  * $Id$
+ * @package squirrelmail
  */
 
+/**
+ * Store the addressbook in a local file
+ */
 class abook_local_file extends addressbook_backend {
     var $btype = 'local';
     var $bname = 'local_file';
@@ -384,4 +388,4 @@ class abook_local_file extends addressbook_backend {
     }
 
 } /* End of class abook_local_file */
-?>
+?>

functions/addressbook.php

@@ -9,9 +9,10 @@
  * Functions and classes for the addressbook system.
  *
  * $Id$
+ * @package squirrelmail
  */
 
-/*
+/**
    This is the path to the global site-wide addressbook.
    It looks and feels just like a user's .abook file
    If this is in the data directory, use "$data_dir/global.abook"
@@ -31,7 +32,7 @@
 
 global $addrbook_dsn;
 
-/*
+/**
    Create and initialize an addressbook object.
    Returns the created object
 */

functions/attachment_common.php

@@ -9,8 +9,12 @@
  * This file provides the handling of often-used attachment types.
  *
  * $Id$
+ * @package squirrelmail
  */
 
+/**
+ * Needs documentation
+ */
 require_once(SM_PATH . 'functions/global.php');
 
 global $attachment_common_show_images_list;

functions/auth.php

@@ -9,9 +9,10 @@
  * Contains functions used to do authentication.
  *
  * $Id$
+ * @package squirrelmail
  */
 
-/* Put in a safety net here, in case a naughty admin didn't run conf.pl when they upgraded */
+/** Put in a safety net here, in case a naughty admin didn't run conf.pl when they upgraded */
 
 if (! isset($smtp_auth_mech)) {
   $smtp_auth_mech = 'none';

functions/constants.php

@@ -11,8 +11,10 @@
  * src/load_prefs.php.
  *
  * $Id$
+ * @package squirrelmail
  */
 
+/** Need to enable plugin functions for a hook */
 require_once(SM_PATH . 'functions/plugin.php');  /* Required for the hook */
 
 /**************************************************************/

functions/date.php

@@ -12,11 +12,13 @@
  * (as specified in RFC 822) -- 'Tue' is optional
  *
  * $Id$
+ * @package squirrelmail
  */
 
+/** Load up some useful constants */
 require_once(SM_PATH . 'functions/constants.php');
 
-/* corrects a time stamp to be the local time */
+/** corrects a time stamp to be the local time */
 function getGMTSeconds($stamp, $tzc) {
     /* date couldn't be parsed */
     if ($stamp == -1) {

functions/db_prefs.php

@@ -1,6 +1,6 @@
 <?php
 
-/*
+/**
  * db_prefs.php
  *
  * Copyright (c) 1999-2003 The SquirrelMail Project Team
@@ -26,10 +26,14 @@
  * by using conf.pl or the administrator plugin
  *
  * $Id$
+ * @package squirrelmail
  */
 
+/** Unknown database */
 define('SMDB_UNKNOWN', 0);
+/** MySQL */
 define('SMDB_MYSQL', 1);
+/** PostgreSQL */
 define('SMDB_PGSQL', 2);
 
 require_once('DB.php');
@@ -67,6 +71,10 @@ function cachePrefValues($username) {
     sqsession_register($prefs_are_cached, 'prefs_are_cached');
 }
 
+/**
+ * Completely undocumented class - someone document it!
+ * @package squirrelmail
+ */
 class dbPrefs {
     var $table = 'userprefs';
     var $user_field = 'user';

functions/decode/big5.php

@@ -1,6 +1,6 @@
 <?php
 
-/*
+/**
  * decode/big5.php
  * $Id$
  *
@@ -34,9 +34,15 @@
  * in the creation of products supporting Unicode.  Unicode, Inc.
  * specifically excludes the right to re-distribute this file directly
  * to third parties or other organizations whether for profit or not.
- *
+ * @package squirrelmail
+ * @subpackage decode
  */
 
+/**
+ * Decode big5 encoded string
+ * @param string $string big5 string
+ * @return string $string decoded string
+ */
 function charset_decode_big5 ($string) {
     global $default_charset;
 
@@ -13765,4 +13771,4 @@ function charset_decode_big5 ($string) {
     return $string;
 }
 
-?>
+?>

functions/decode/cp10000.php

@@ -1,5 +1,5 @@
 <?php
-/*
+/**
  * decode/cp10000.php
  * $Id$
  *
@@ -19,8 +19,15 @@
  *  Date:          04/24/96
  *  Authors:       Lori Brownell <loribr@microsoft.com>
  *                 K.D. Chang    <a-kchang@microsoft.com>
+ * @package squirrelmail
+ * @subpackage decode
  */
 
+/**
+ * Decode cp10000 (MacRoman) string
+ * @param string $string String to decode
+ * @return string $string Decoded string
+ */
 function charset_decode_cp10000 ($string) {
     global $default_charset;
 
@@ -167,4 +174,4 @@ function charset_decode_cp10000 ($string) {
 
     return $string;
 }
-?>
+?>

functions/decode/cp10006.php

@@ -1,5 +1,5 @@
 <?php
-/*
+/**
  * decode/cp10006.php
  * $Id$
  *
@@ -19,8 +19,15 @@
  *  Date:          04/24/96
  *  Authors:       Lori Brownell <loribr@microsoft.com>
  *                 K.D. Chang    <a-kchang@microsoft.com>
+ * @package squirrelmail
+ * @subpackage decode
  */
 
+/**
+ * Decode cp10006 (MacGreek) string
+ * @param string $string String to decode
+ * @return string $string Decoded string
+ */
 function charset_decode_cp10006 ($string) {
     global $default_charset;
 
@@ -167,4 +174,4 @@ function charset_decode_cp10006 ($string) {
 
     return $string;
 }
-?>
+?>

functions/decode/cp10007.php

@@ -1,5 +1,5 @@
 <?php
-/*
+/**
  * decode/cp10007.php
  * $Id$
  *
@@ -19,9 +19,15 @@
  *   Date:          04/24/96
  *   Authors:       Lori Brownell <loribr@microsoft.com>
  *          K.D. Chang    <a-kchang@microsoft.com>
- *
+ * @package squirrelmail
+ * @subpackage decode
  */
 
+/**
+ * Decode cp10007 (MacCyrillic) string
+ * @param string $string MacCyrillic string to decode
+ * @return string $string Decoded string
+ */
 function charset_decode_cp10007 ($string) {
     global $default_charset;
 
@@ -168,4 +174,4 @@ function charset_decode_cp10007 ($string) {
 
     return $string;
 }
-?>
+?>

functions/decode/cp10017.php

@@ -1,5 +1,5 @@
 <?php
-/*
+/**
  * decode/cp10017.php
  * $Id$
  *
@@ -18,8 +18,15 @@
  * 1. ftp://ftp.unicode.org/Public/MAPPINGS/VENDORS/MICSFT/MAC/CYRILLIC.TXT
  * 2. http://developer.apple.com/documentation/macos8/TextIntlSvcs/TextEncodingConversionManager/TEC1.5/TEC.b0.html
  * 3. http://shlimazl.nm.ru/rus/cptable.htm (page in Russian)
+ * @package squirrelmail
+ * @subpackage decode
  */
 
+/**
+ * Decode a cp10017 (MacUkrainian) string
+ * @param string $string Encoded string
+ * @return string $string Decoded string
+ */
 function charset_decode_cp10017 ($string) {
     global $default_charset;
 
@@ -166,4 +173,4 @@ function charset_decode_cp10017 ($string) {
 
     return $string;
 }
-?>
+?>

functions/decode/cp10029.php

@@ -1,5 +1,5 @@
 <?php
-/*
+/**
  * decode/cp10029.php
  * $Id$
  *
@@ -19,8 +19,15 @@
  *  Date:          04/24/96
  *  Authors:       Lori Brownell <loribr@microsoft.com>
  *                 K.D. Chang    <a-kchang@microsoft.com>
+ * @package squirrelmail
+ * @subpackage decode
  */
 
+/**
+ * Decode cp10029 (MacLatin2) string
+ * @param string $string Encoded string
+ * @return string $string Decoded string
+ */
 function charset_decode_cp10029 ($string) {
     global $default_charset;
 
@@ -167,4 +174,4 @@ function charset_decode_cp10029 ($string) {
 
     return $string;
 }
-?>
+?>

functions/decode/cp10079.php

@@ -1,5 +1,5 @@
 <?php
-/*
+/**
  * decode/cp10079.php
  * $Id$
  *
@@ -19,8 +19,15 @@
  *  Date:          04/24/96
  *  Authors:       Lori Brownell <loribr@microsoft.com>
  *                 K.D. Chang    <a-kchang@microsoft.com>
+ * @package squirrelmail
+ * @subpackage decode
  */
 
+/**
+ * Decode a cp10079 (MacIcelandic) string
+ * @param string $string Encoded string
+ * @return string $string Decoded string
+ */
 function charset_decode_cp10079 ($string) {
     global $default_charset;
 
@@ -167,4 +174,4 @@ function charset_decode_cp10079 ($string) {
 
     return $string;
 }
-?>
+?>

functions/decode/cp10081.php

@@ -1,5 +1,5 @@
 <?php
-/*
+/**
  * decode/cp10081.php
  * $Id$
  *
@@ -19,8 +19,15 @@
  *  Date:          04/24/96
  *  Authors:       Lori Brownell <loribr@microsoft.com>
  *                 K.D. Chang    <a-kchang@microsoft.com>
+ * @package squirrelmail
+ * @subpackage decode
  */
 
+/**
+ * Decode cp10081(MacTurkish) encoded string
+ * @param string $string Encoded string
+ * @return string $string Decoded string
+ */
 function charset_decode_cp10081 ($string) {
     global $default_charset;
 
@@ -167,4 +174,4 @@ function charset_decode_cp10081 ($string) {
 
     return $string;
 }
-?>
+?>

functions/decode/cp1250.php

@@ -1,5 +1,5 @@
 <?php
-/*
+/**
  * decode/cp1250.php
  * $Id$
  *
@@ -18,9 +18,15 @@
  *  Table format:  Format A
  *  Date:          04/15/98
  *  Contact:       cpxlate@microsoft.com
- *
+ * @package squirrelmail
+ * @subpackage decode
  */
 
+/**
+ * Decode a cp1250 string
+ * @param string $string Encoded string
+ * @return string $string Decoded string
+ */
 function charset_decode_cp1250 ($string) {
     global $default_charset;
 
@@ -168,4 +174,4 @@ function charset_decode_cp1250 ($string) {
     return $string;
 }
 
-?>
+?>

functions/decode/cp1251.php

@@ -1,5 +1,5 @@
 <?php
-/*
+/**
  * decode/cp1251.php
  * $Id$
  *
@@ -18,9 +18,15 @@
  *   Table format:  Format A
  *   Date:          04/15/98
  *   Contact:       cpxlate@microsoft.com
- *
+ * @package squirrelmail
+ * @subpackage decode
  */
 
+/**
+ * Decode cp1251-encoded string
+ * @param string $string Encoded string
+ * @return string $string Decoded string
+ */
 function charset_decode_cp1251 ($string) {
     global $default_charset;
 
@@ -168,4 +174,4 @@ function charset_decode_cp1251 ($string) {
     return $string;
 }
 
-?>
+?>

functions/decode/cp1252.php

@@ -1,5 +1,5 @@
 <?php
-/*
+/**
  * decode/cp1252.php
  * $Id$
  *
@@ -18,7 +18,14 @@
  *   Table format:  Format A
  *   Date:          04/15/98
  *   Contact:       cpxlate@microsoft.com
- *
+ * @package squirrelmail
+ * @subpackage decode
+ */
+
+/**
+ * Decode cp1252-encoded string
+ * @param string $string Encoded string
+ * @return string $string Decoded string
  */
 
 function charset_decode_cp1252 ($string) {
@@ -168,4 +175,4 @@ function charset_decode_cp1252 ($string) {
     return $string;
 }
 
-?>
+?>

functions/decode/cp1253.php

@@ -1,5 +1,5 @@
 <?php
-/*
+/**
  * decode/cp1253.php
  * $Id$
  *
@@ -18,9 +18,15 @@
  *   Table format:  Format A
  *   Date:          04/15/98
  *   Contact:       cpxlate@microsoft.com
- *
+ * @package squirrelmail
+ * @subpackage decode
  */
 
+/**
+ * Decode cp1253-encoded string
+ * @param string $string Encoded string
+ * @return string $string Decoded string
+ */
 function charset_decode_cp1253 ($string) {
     global $default_charset;
 
@@ -168,4 +174,4 @@ function charset_decode_cp1253 ($string) {
     return $string;
 }
 
-?>
+?>

functions/decode/cp1254.php

@@ -1,5 +1,5 @@
 <?php
-/*
+/**
  * decode/cp1254.php
  * $Id$
  *
@@ -18,9 +18,15 @@
  *   Table format:  Format A
  *   Date:          04/15/98
  *   Contact:       cpxlate@microsoft.com
- *
+ * @package squirrelmail
+ * @subpackage decode
  */
 
+/**
+ * Decode cp1254-encoded string
+ * @param string $string Encoded string
+ * @return string $string Decoded string
+ */
 function charset_decode_cp1254 ($string) {
     global $default_charset;
 
@@ -168,4 +174,4 @@ function charset_decode_cp1254 ($string) {
     return $string;
 }
 
-?>
+?>

functions/decode/cp1255.php

@@ -1,5 +1,5 @@
 <?php
-/*
+/**
  * decode/cp1255.php
  * $Id$
  *
@@ -18,9 +18,15 @@
  *   Table format:  Format A
  *   Date:          1/7/2000
  *   Contact:       cpxlate@microsoft.com
- *
+ * @package squirrelmail
+ * @subpackage decode
  */
 
+/**
+ * Decode cp1255-encoded string
+ * @param string $string Encoded string
+ * @return string $string decoded string
+ */
 function charset_decode_cp1255 ($string) {
     global $default_charset;
 
@@ -168,4 +174,4 @@ function charset_decode_cp1255 ($string) {
     return $string;
 }
 
-?>
+?>

functions/decode/cp1256.php

@@ -1,5 +1,5 @@
 <?php
-/*
+/**
  * decode/cp1256.php
  * $Id$
  *
@@ -18,9 +18,15 @@
  *   Table format:  Format A
  *   Date:          01/5/99
  *   Contact:       cpxlate@microsoft.com
- *
+ * @package squirrelmail
+ * @subpackage decode
  */
 
+/**
+ * decode cp1256-encoded string
+ * @param string $string Encoded string
+ * @return string $string Decoded string
+ */
 function charset_decode_cp1256 ($string) {
     global $default_charset;
 
@@ -168,4 +174,4 @@ function charset_decode_cp1256 ($string) {
     return $string;
 }
 
-?>
+?>

functions/decode/cp1257.php

@@ -1,5 +1,5 @@
 <?php
-/*
+/**
  * decode/cp1257.php
  * $Id$
  *
@@ -18,9 +18,15 @@
  *  Table format:  Format A
  *  Date:          04/15/98
  *  Contact:       cpxlate@microsoft.com
- *
+ * @package squirrelmail
+ * @subpackage decode
  */
 
+/**
+ * Decode cp1257-encoded string
+ * @param string $string Encoded string
+ * @return string $string Decoded string
+ */
 function charset_decode_cp1257 ($string) {
     global $default_charset;
 
@@ -156,4 +162,4 @@ function charset_decode_cp1257 ($string) {
     return $string;
 }
 
-?>
+?>

functions/decode/cp1258.php

@@ -1,5 +1,5 @@
 <?php
-/*
+/**
  * decode/cp1258.php
  * $Id$
  *
@@ -18,9 +18,15 @@
  *   Table format:  Format A
  *   Date:          04/15/98
  *   Contact:       cpxlate@microsoft.com
- *
+ * @package squirrelmail
+ * @subpackage decode
  */
 
+/**
+ * Decde a cp1258-encoded string
+ * @param string $string Encoded string
+ * @return string $string Decoded string
+ */
 function charset_decode_cp1258 ($string) {
     global $default_charset;
 
@@ -168,4 +174,4 @@ function charset_decode_cp1258 ($string) {
     return $string;
 }
 
-?>
+?>

functions/decode/cp855.php

@@ -1,5 +1,5 @@
 <?php
-/*
+/**
  * decode/cp855.php
  * $Id$
  *
@@ -18,8 +18,15 @@
  *   Date:          04/24/96
  *   Authors:       Lori Brownell <loribr@microsoft.com>
  *                  K.D. Chang    <a-kchang@microsoft.com>
+ * @package squirrelmail
+ * @subpackage decode
  */
 
+/**
+ * Decode a cp855-encoded string
+ * @param string $string Encoded string
+ * @return string $string Decoded string
+ */
 function charset_decode_cp855 ($string) {
     global $default_charset;
 
@@ -167,4 +174,4 @@ function charset_decode_cp855 ($string) {
     return $string;
 }
 
-?>
+?>

functions/decode/cp866.php

@@ -1,5 +1,5 @@
 <?php
-/*
+/**
  * decode/cp866.php
  * $Id$
  *
@@ -20,9 +20,15 @@
     Authors:       Lori Brownell <loribr@microsoft.com>
                    K.D. Chang    <a-kchang@microsoft.com>
     The entries are in cp866_DOSCyrillicRussian order
+ * @package squirrelmail
+ * @subpackage decode
 */
 
-
+/**
+ * Decode a cp866-encoded string
+ * @param string $string Encoded string
+ * @return string $string Decoded string
+ */
 function charset_decode_cp866 ($string) {
     global $default_charset;
 

functions/decode/gb2312.php

@@ -1,5 +1,5 @@
 <?php
-/*
+/**
  * decode/gb2312.php
  * $Id$
  *
@@ -33,7 +33,15 @@
  * Unicode Standard, and to make copies of this file in any form for
  * internal or external distribution as long as this notice remains
  * attached.
- *
+ * @package squirrelmail
+ * @subpackage decode
+ */
+
+
+/**
+ * Decode gb2312-euk encoded string
+ * @param string $string Encoded string
+ * @return string $string Decoded string
  */
 function charset_decode_gb2312 ($string) {
     global $default_charset;
@@ -7498,4 +7506,4 @@ function charset_decode_gb2312 ($string) {
     return $string;
 }
 
-?>
+?>

functions/decode/iso-ir-111.php

@@ -1,5 +1,5 @@
 <?php
-/*
+/**
  * decode/iso-ir-111.php
  * $Id$
  *
@@ -39,8 +39,16 @@
  * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT
  * OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR
  * THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ *
+ * @package squirrelmail
+ * @subpackage decode
  */
 
+/**
+ * Decode iso-ir-111 encoded strings
+ * @param string $string Encoded string
+ * @return string Decoded string
+ */
 function charset_decode_iso_ir_111 ($string) {
     global $default_charset;
 
@@ -156,4 +164,4 @@ function charset_decode_iso_ir_111 ($string) {
     return $string;
 }
 
-?>
+?>

functions/decode/iso8859-1.php

@@ -1,5 +1,5 @@
 <?php
-/*
+/**
  * decode/iso8859-1.php
  * $Id$
  *
@@ -8,7 +8,14 @@
  *
  * This file contains iso-8859-1 decoding function that is needed to read
  * iso-8859-1 encoded mails in non-iso-8859-1 locale.
- * 
+ * @package squirrelmail
+ * @subpackage decode
+ */
+
+/**
+ * Decode iso8859-1 string
+ * @param string $string Encoded string
+ * @return string $string Decoded string
  */
 function charset_decode_iso8859_1 ($string) {
     global $default_charset;
@@ -30,4 +37,4 @@ function charset_decode_iso8859_1 ($string) {
     return $string;
 }
 
-?>
+?>

functions/decode/iso8859-10.php

@@ -1,5 +1,5 @@
 <?php
-/*
+/**
  * decode/iso8859-10.php
  * $Id$
  *
@@ -35,7 +35,14 @@
  *	Unicode Standard, and to make copies of this file in any form for
  *	internal or external distribution as long as this notice remains
  *	attached.
- *
+ * @package squirrelmail
+ * @subpackage decode
+ */
+
+/**
+ * Decode iso-8859-10 encoded string
+ * @param string $string Encoded string
+ * @return string $string Decoded string
  */
 function charset_decode_iso8859_10 ($string) {
     global $default_charset;
@@ -152,4 +159,4 @@ function charset_decode_iso8859_10 ($string) {
     return $string;
 }
 
-?>
+?>

functions/decode/iso8859-11.php

@@ -1,5 +1,5 @@
 <?php
-/*
+/**
  * decode/iso8859-11.php
  * $Id$
  *
@@ -35,7 +35,14 @@
  *	Unicode Standard, and to make copies of this file in any form for
  *	internal or external distribution as long as this notice remains
  *	attached.
- *
+ * @package squirrelmail
+ * @subpackage decode
+ */
+
+/**
+ * Decode iso8859-11 string
+ * @param string $string Encoded string
+ * @return string $string Decoded string 
  */
 function charset_decode_iso8859_11 ($string) {
     global $default_charset;
@@ -144,4 +151,4 @@ function charset_decode_iso8859_11 ($string) {
     return $string;
 }
 
-?>
+?>

functions/decode/iso8859-13.php

@@ -1,5 +1,5 @@
 <?php
-/*
+/**
  * decode/iso8859-13.php
  * $Id$
  *
@@ -35,7 +35,14 @@
  *	Unicode Standard, and to make copies of this file in any form for
  *	internal or external distribution as long as this notice remains
  *	attached.
- *
+ * @package squirrelmail
+ * @subpackage decode
+ */
+
+/**
+ * Decode iso8859-13
+ * @param string $string Encoded string
+ * @return string $string Decoded string
  */
 function charset_decode_iso8859_13 ($string) {
     global $default_charset;
@@ -152,4 +159,4 @@ function charset_decode_iso8859_13 ($string) {
     return $string;
 }
 
-?>
+?>

functions/decode/iso8859-14.php

@@ -1,5 +1,5 @@
 <?php
-/*
+/**
  * decode/iso8859-14.php
  * $Id$
  *
@@ -36,7 +36,14 @@
  *	Unicode Standard, and to make copies of this file in any form for
  *	internal or external distribution as long as this notice remains
  *	attached.
- *
+ * @package squirrelmail
+ * @subpackage decode
+ */
+
+/**
+ * Decode iso8859-14 encoded string
+ * @param string $string Encoded string
+ * @return string $string Decoded string 
  */
 function charset_decode_iso8859_14 ($string) {
     global $default_charset;
@@ -153,4 +160,4 @@ function charset_decode_iso8859_14 ($string) {
     return $string;
 }
 
-?>
+?>

functions/decode/iso8859-15.php

@@ -1,5 +1,5 @@
 <?php
-/*
+/**
  * decode/iso8859-15.php
  * $Id$
  *
@@ -36,7 +36,14 @@
  *	Unicode Standard, and to make copies of this file in any form for
  *	internal or external distribution as long as this notice remains
  *	attached.
- *
+ * @package squirrelmail
+ * @subpackage decode
+ */
+
+/**
+ * Decode iso8859-15 encoded string
+ * @param string $string Encoded string
+ * @return string $string Decoded string
  */
 function charset_decode_iso8859_15 ($string) {
     global $default_charset;
@@ -153,4 +160,4 @@ function charset_decode_iso8859_15 ($string) {
     return $string;
 }
 
-?>
+?>

functions/decode/iso8859-16.php

@@ -1,5 +1,5 @@
 <?php
-/*
+/**
  * decode/iso8859-16.php
  * $Id$
  *
@@ -35,7 +35,14 @@
  *	Unicode Standard, and to make copies of this file in any form for
  *	internal or external distribution as long as this notice remains
  *	attached.
- *
+ * @package squirrelmail
+ * @subpackage decode
+ */
+
+/**
+ * Decode iso8859-16 string
+ * @param string $string Encoded string
+ * @return string $string Decoded string
  */
 function charset_decode_iso8859_16 ($string) {
     global $default_charset;
@@ -152,4 +159,4 @@ function charset_decode_iso8859_16 ($string) {
     return $string;
 }
 
-?>
+?>

functions/decode/iso8859-2.php

@@ -1,5 +1,5 @@
 <?php
-/*
+/**
  * decode/iso8859-2.php
  * $Id$
  *
@@ -35,7 +35,14 @@
  *	Unicode Standard, and to make copies of this file in any form for
  *	internal or external distribution as long as this notice remains
  *	attached.
- *
+ * @package squirrelmail
+ * @subpackage decode
+ */
+
+/**
+ * Decode iso8859-2 encoded string
+ * @param string $string Encoded string
+ * @return string $string Decoded string
  */
 function charset_decode_iso8859_2 ($string) {
     global $default_charset;
@@ -152,4 +159,4 @@ function charset_decode_iso8859_2 ($string) {
     return $string;
 }
 
-?>
+?>

functions/decode/iso8859-3.php

@@ -1,5 +1,5 @@
 <?php
-/*
+/**
  * decode/iso8859-3.php
  * $Id$
  *
@@ -35,7 +35,14 @@
  *	Unicode Standard, and to make copies of this file in any form for
  *	internal or external distribution as long as this notice remains
  *	attached.
- *
+ * @package squirrelmail
+ * @subpackage decode
+ */
+
+/**
+ * Decode iso8859-3 encoded string
+ * @param string $string Encoded string
+ * @return string $string Decoded string
  */
 function charset_decode_iso8859_3 ($string) {
     global $default_charset;
@@ -145,4 +152,4 @@ function charset_decode_iso8859_3 ($string) {
     return $string;
 }
 
-?>
+?>

functions/decode/iso8859-4.php

@@ -1,5 +1,5 @@
 <?php
-/*
+/**
  * decode/iso8859-4.php
  * $Id$
  *
@@ -35,7 +35,14 @@
  *	Unicode Standard, and to make copies of this file in any form for
  *	internal or external distribution as long as this notice remains
  *	attached.
- *
+ * @package squirrelmail
+ * @subpackage decode
+ */
+
+/**
+ * Decode iso8859-4 string
+ * @param string $string Encoded string
+ * @return string $string Decoded string
  */
 function charset_decode_iso8859_4 ($string) {
     global $default_charset;
@@ -152,4 +159,4 @@ function charset_decode_iso8859_4 ($string) {
     return $string;
 }
 
-?>
+?>

functions/decode/iso8859-5.php

@@ -1,5 +1,5 @@
 <?php
-/*
+/**
  * decode/iso8859-5.php
  * $Id$
  *
@@ -35,7 +35,14 @@
  *	Unicode Standard, and to make copies of this file in any form for
  *	internal or external distribution as long as this notice remains
  *	attached.
- *
+ * @package squirrelmail
+ * @subpackage decode
+ */
+
+/**
+ * Decode iso8859-5 encoded string
+ * @param string $string Encoded string
+ * @return string $string Decoded string
  */
 function charset_decode_iso8859_5 ($string) {
     global $default_charset;
@@ -152,4 +159,4 @@ function charset_decode_iso8859_5 ($string) {
     return $string;
 }
 
-?>
+?>

functions/decode/iso8859-6.php

@@ -1,5 +1,5 @@
 <?php
-/*
+/**
  * decode/iso8859-6.php
  * $Id$
  *
@@ -35,7 +35,14 @@
  *	Unicode Standard, and to make copies of this file in any form for
  *	internal or external distribution as long as this notice remains
  *	attached.
- *
+ * @package squirrelmail
+ * @subpackage decode
+ */
+
+/**
+ * Decode iso8859-6 strings
+ * @param string $string Encoded string
+ * @return string $string Decoded string
  */
 function charset_decode_iso8859_6 ($string) {
     global $default_charset;
@@ -107,4 +114,4 @@ function charset_decode_iso8859_6 ($string) {
     return $string;
 }
 
-?>
+?>

functions/decode/iso8859-7.php

@@ -1,5 +1,5 @@
 <?php
-/*
+/**
  * decode/iso8859-7.php
  * $Id$
  *
@@ -35,7 +35,14 @@
  *	Unicode Standard, and to make copies of this file in any form for
  *	internal or external distribution as long as this notice remains
  *	attached.
- *
+ * @package squirrelmail
+ * @subpackage decode
+ */
+
+/**
+ * Decode iso8859-7 encoded strings
+ * @param string $string Encoded string
+ * @return string $string Decoded string
  */
 function charset_decode_iso8859_7 ($string) {
     global $default_charset;
@@ -146,4 +153,4 @@ function charset_decode_iso8859_7 ($string) {
     return $string;
 }
 
-?>
+?>

functions/decode/iso8859-8.php

@@ -1,5 +1,5 @@
 <?php
-/*
+/**
  * decode/iso8859-8.php
  * $Id$
  *
@@ -35,7 +35,14 @@
  *	Unicode Standard, and to make copies of this file in any form for
  *	internal or external distribution as long as this notice remains
  *	attached.
- *
+ * @package squirrelmail
+ * @subpackage decode
+ */
+
+/**
+ * Decode iso8859-8 encoded strings
+ * @param string $string Encoded string
+ * @return string $string Decoded string
  */
 function charset_decode_iso8859_8 ($string) {
     global $default_charset;
@@ -116,4 +123,4 @@ function charset_decode_iso8859_8 ($string) {
     return $string;
 }
 
-?>
+?>

functions/decode/iso8859-9.php

@@ -1,5 +1,5 @@
 <?php
-/*
+/**
  * decode/iso8859-9.php
  * $Id$
  *
@@ -35,7 +35,14 @@
  *	Unicode Standard, and to make copies of this file in any form for
  *	internal or external distribution as long as this notice remains
  *	attached.
- *
+ * @package squirrelmail
+ * @subpackage decode
+ */
+
+/**
+ * Decode iso8859-9 encoded strings
+ * @param string $string Encoded string
+ * @return string Decoded string
  */
 function charset_decode_iso8859_9 ($string) {
     global $default_charset;
@@ -152,4 +159,4 @@ function charset_decode_iso8859_9 ($string) {
     return $string;
 }
 
-?>
+?>

functions/decode/koi8-r.php

@@ -1,5 +1,5 @@
 <?php
-/*
+/**
  * decode/koi8-r.php
  * $Id$
  *
@@ -35,8 +35,15 @@
  * internal or external distribution as long as this notice remains
  * attached.
  *
+ * @package squirrelmail
+ * @subpackage decode
  */
 
+/**
+ * Decode koi8r strings
+ * @param string $string Encoded string
+ * @return string Decoded string
+ */
 function charset_decode_koi8r ($string) {
     global $default_charset;
 
@@ -184,4 +191,4 @@ function charset_decode_koi8r ($string) {
     return $string;
 }
 
-?>
+?>

functions/decode/koi8-u.php

@@ -1,5 +1,5 @@
 <?php
-/*
+/**
  * decode/koi8-u.php
  * $Id$
  *
@@ -39,6 +39,14 @@
  * HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
  * MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
  *
+ * @package squirrelmail
+ * @subpackage decode
+ */
+
+/**
+ * Decode koi8-u encoded strings
+ * @param string $string Encoded string
+ * @return string Decoded string
  */
 function charset_decode_koi8u ($string) {
     global $default_charset;
@@ -187,4 +195,4 @@ function charset_decode_koi8u ($string) {
     return $string;
 }
 
-?>
+?>

functions/decode/tis620.php

@@ -1,5 +1,5 @@
 <?php
-/*
+/**
  * decode/tis620.php
  * $Id$
  *
@@ -34,6 +34,14 @@
  *  5. http://charts.unicode.org/Unicode.charts/normal/U0E00.html
  *  6. http://www.unicode.org/
  *
+ * @package squirrelmail
+ * @subpackage decode
+ */
+
+/**
+ * Decode tis620 encoded strings
+ * @param string $string Encoded string
+ * @return string Decoded string
  */
 function charset_decode_tis620 ($string) {
     global $default_charset;
@@ -150,4 +158,4 @@ function charset_decode_tis620 ($string) {
     return $string;
 }
 
-?>
+?>

functions/decode/utf-8.php

@@ -1,5 +1,5 @@
 <?php
-/*
+/**
  * decode/utf-8.php
  * $Id$
  *
@@ -17,6 +17,14 @@
  *
  * decoding cycle is unfinished. please test and report problems to tokul@users.sourceforge.net
  * 
+ * @package squirrelmail
+ * @subpackage decode
+ */
+
+/**
+ * Decode utf-8 strings
+ * @param string $string Encoded string
+ * @return string Decoded string
  */
 function charset_decode_utf8 ($string) {
   global $default_charset;
@@ -42,4 +50,4 @@ function charset_decode_utf8 ($string) {
     return $string;
 }
 
-?>
+?>

functions/display_messages.php

@@ -10,6 +10,7 @@
  * about any other message you can think of.
  *
  * $Id$
+ * @package squirrelmail
  */
 
 /**
@@ -18,7 +19,7 @@
  * called "src", "functions", or "plugins", but people who do that need
  * to be beaten with a steel pipe anyway.
  *
- * @return  the base uri of squirrelmail installation.
+ * @return string the base uri of squirrelmail installation.
  */
 function sqm_baseuri(){
     global $base_uri, $PHP_SELF;

functions/file_prefs.php

@@ -9,9 +9,10 @@
  * This contains functions for manipulating user preferences in files
  *
  * $Id$
+ * @package squirrelmail
  */
 
-/* include this for error messages */
+/** include this for error messages */
 include_once(SM_PATH . 'functions/display_messages.php');
 
 /**

functions/gettext.php

@@ -13,8 +13,10 @@
  *   $sm_language, I think
  *
  * $Id$
+ * @package squirrelmail
  */
 
+/** Almost everything requires global.php... */
 require_once(SM_PATH . 'functions/global.php');
 
 global $gettext_php_domain, $gettext_php_dir, $gettext_php_loaded,

functions/global.php

@@ -11,21 +11,23 @@
  * php versions. 
  *
  * $Id$
+ * @package squirrelmail
  */
 
+/** Bring in the config file. */
 require_once(SM_PATH . 'config/config.php');
 
-/* set the name of the session cookie */
+/** set the name of the session cookie */
 if(isset($session_name) && $session_name) {  
     ini_set('session.name' , $session_name);  
 } else {  
     ini_set('session.name' , 'SQMSESSID');  
 }
 
-/* If magic_quotes_runtime is on, SquirrelMail breaks in new and creative ways.
- * Force magic_quotes_runtime off.
- * tassium@squirrelmail.org - I put it here in the hopes that all SM code includes this.
- * If there's a better place, please let me know.
+/** If magic_quotes_runtime is on, SquirrelMail breaks in new and creative ways.
+ *  Force magic_quotes_runtime off.
+ *  tassium@squirrelmail.org - I put it here in the hopes that all SM code includes this.
+ *  If there's a better place, please let me know.
  */
 ini_set('magic_quotes_runtime','0');
 

functions/html.php

@@ -11,9 +11,20 @@
  * html outputs.
  *
  * $Id$
+ * @package squirrelmail
  */
 
-    function html_tag( $tag,                // Tag to output
+/**
+ * Generate html tags
+ *
+ * @param string $tag Tag to output
+ * @param string $val Value between tags
+ * @param string $align Alignment (left, center, etc)
+ * @param string $bgcolor Back color in hexadecimal
+ * @param string $xtra Extra options
+ * @return string HTML ready for output
+ */
+function html_tag( $tag,                // Tag to output
                        $val = '',           // Value between tags
                        $align = '',         // Alignment
                        $bgcolor = '',       // Back color

functions/i18n.php

@@ -13,11 +13,19 @@
  * encoded using Unicode entities according to HTML 4.0.
  *
  * $Id$
+ * @package squirrelmail
  */
 
+/** Everything uses global.php... */
 require_once(SM_PATH . 'functions/global.php');
 
-/* Decodes a string to the internal encoding from the given charset */
+/**
+ * Decodes a string to the internal encoding from the given charset
+ * 
+ * @param string $charset
+ * @param string $string Text to be decoded
+ * @return string Decoded text
+ */
 function charset_decode ($charset, $string) {
     global $languages, $squirrelmail_language, $default_charset;
     global $use_php_recode, $use_php_iconv, $agresive_decoding;

functions/identity.php

@@ -9,9 +9,10 @@
  * This contains utility functions for dealing with multiple identities
  *
  * $Id$
- *
+ * @package squirrelmail
  */
 
+/** Used to simplify includes */
 if (!defined('SM_PATH')) {
     define('SM_PATH','../');
 }
@@ -21,6 +22,7 @@ include_once(SM_PATH . 'include/load_prefs.php');
 /**
 * Returns an array of all the identities.
 * Array is keyed: full_name, reply_to, email_address, index, signature
+* @return array full_name,reply_to,email_address,index,signature
 */
 function get_identities() {
 

functions/imap.php

@@ -10,8 +10,10 @@
  * They have been organized into these sections for simplicity sake.
  *
  * $Id$
+ * @package squirrelmail
  */
 
+/** Includes */
 require_once(SM_PATH . 'functions/imap_mailbox.php');
 require_once(SM_PATH . 'functions/imap_messages.php');
 require_once(SM_PATH . 'functions/imap_general.php');

functions/imap_asearch.php

@@ -7,15 +7,17 @@
  * Licensed under the GNU GPL. For full terms see the file COPYING.
  *
  * IMAP asearch routines
- * Alex Lemaresquier - Brainstorm - alex at brainstorm.fr
+ * @author Alex Lemaresquier - Brainstorm - alex at brainstorm.fr
  * See README file for infos.
+ * @package squirrelmail
  *
  */
 
+/** This functionality requires the IMAP and date functions */
 require_once(SM_PATH . 'functions/imap_general.php');
 require_once(SM_PATH . 'functions/date.php');
 
-/* Set to TRUE to dump the imap dialogue */
+/** Set to TRUE to dump the imap dialogue */
 $imap_asearch_debug_dump = FALSE;
 
 $imap_asearch_opcodes = array(
@@ -372,4 +374,4 @@ function sqimap_asearch($imapConnection, $mailbox_array, $biop_array, $unop_arra
 	return $mbox_msgs;
 }
 
-?>
+?>

functions/imap_general.php

@@ -9,8 +9,10 @@
  * This implements all functions that do general imap functions.
  *
  * $Id$
+ * @package squirrelmail
  */
 
+/** Includes.. */
 require_once(SM_PATH . 'functions/page_header.php');
 require_once(SM_PATH . 'functions/auth.php');
 

functions/imap_mailbox.php

@@ -9,18 +9,24 @@
  * This impliments all functions that manipulate mailboxes
  *
  * $Id$
+ * @package squirrelmail
  */
+
+/** UTF7 support */
 require_once(SM_PATH . 'functions/imap_utf7_local.php');
 
 global $boxesnew;
 
-/*
-   FIXME. This class should be extracted and placed in a separate file that 
-   can be included before we start the session. That makes caching of the tree
-   possible. On a refresh mailboxes from left_main.php the only function that 
-   should be called is the sqimap_get_status_mbx_tree. In case of subscribe 
-   / rename / delete / new we have to create methods for adding/changing the 
-   mailbox in the mbx_tree without the need for a refresh.
+/**
+ * Mailboxes class
+ * 
+ * FIXME. This class should be extracted and placed in a separate file that 
+ * can be included before we start the session. That makes caching of the tree
+ * possible. On a refresh mailboxes from left_main.php the only function that 
+ * should be called is the sqimap_get_status_mbx_tree. In case of subscribe 
+ * / rename / delete / new we have to create methods for adding/changing the 
+ * mailbox in the mbx_tree without the need for a refresh.
+ * @package squirrelmail
 */
 
 class mailboxes {

functions/imap_messages.php

@@ -7,14 +7,20 @@
  * Licensed under the GNU GPL. For full terms see the file COPYING.
  *
  * This implements functions that manipulate messages
+ * NOTE: Quite a few functions in this file are obsolete
  *
  * $Id$
+ * @package squirrelmail
  */
 
-/* NOTE: quite some functions in this file are not used anymore. */
-
-/* Copies specified messages to specified folder */
-/* obsolete */
+/**
+ * Copies specified messages to specified folder
+ * @param int $imap_stream The resource ID for the IMAP connection
+ * @param string $start Beginning of range to copy
+ * @param string $end End of the range to copy
+ * @param string $mailbox Which box to copy to
+ * @deprecated This function is obsolete and should not be used
+ */
 function sqimap_messages_copy ($imap_stream, $start, $end, $mailbox) {
     global $uid_support;
     $read = sqimap_run_command ($imap_stream, "COPY $start:$end " . sqimap_encode_mailbox_name($mailbox), true, $response, $message, $uid_support);
@@ -22,6 +28,10 @@ function sqimap_messages_copy ($imap_stream, $start, $end, $mailbox) {
 
 /**
 * copy a range of messages ($id) to another mailbox ($mailbox)
+* @param int $imap_stream The resource ID for the IMAP socket
+* @param string $id The list of messages to copy
+* @param string $mailbox The destination to copy to
+* @return void
 */
 function sqimap_msgs_list_copy ($imap_stream, $id, $mailbox) {
     global $uid_support;
@@ -31,6 +41,10 @@ function sqimap_msgs_list_copy ($imap_stream, $id, $mailbox) {
 
 /**
 * move a range of messages ($id) to another mailbox. Deletes the originals.
+* @param int $imap_stream The resource ID for the IMAP socket
+* @param string $id The list of messages to move
+* @param string $mailbox The destination to move to
+* @return void
 */
 function sqimap_msgs_list_move ($imap_stream, $id, $mailbox) {
     global $uid_support;
@@ -40,8 +54,15 @@ function sqimap_msgs_list_move ($imap_stream, $id, $mailbox) {
 }
 
 
-/* Deletes specified messages and moves them to trash if possible */
-/* obsolete */
+/**
+ * Deletes specified messages and moves them to trash if possible
+ * @deprecated This function is obsolete and should no longer be used
+ * @param int $imap_steam The resource ID for the IMAP connection
+ * @param string $start Start of range
+ * @param string $end End of range
+ * @param string $mailbox Mailbox messages are being deleted from
+ * @return void
+ */
 function sqimap_messages_delete ($imap_stream, $start, $end, $mailbox) {
     global $move_to_trash, $trash_folder, $auto_expunge, $uid_support;
 
@@ -61,7 +82,9 @@ function sqimap_msgs_list_delete ($imap_stream, $mailbox, $id, $bypass_trash=fal
 }
 
 
-/* Sets the specified messages with specified flag */
+/**
+ * Sets the specified messages with specified flag
+ */
 function sqimap_messages_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);

functions/imap_search.php

@@ -9,8 +9,12 @@
  * IMAP search routines
  *
  * $Id$
+ * @package squirrelmail
+ * @deprecated This search interface has been largely replaced by asearch
  */
 
+/**
+ * Load up a bunch of SM functions */
 require_once(SM_PATH . 'functions/imap.php');
 require_once(SM_PATH . 'functions/date.php');
 require_once(SM_PATH . 'functions/mailbox_display.php');

functions/imap_utf7_local.php

@@ -9,8 +9,16 @@
  * This implements all functions that do imap UTF7 conversions.
  *
  * $Id$
+ * @package squirrelmail
  */
 
+/**
+ * @param string $str
+ * @param string $to_encoding
+ * @param string $from_encoding
+ * @param string $default_charset
+ * @return string
+ */
 function sqimap_mb_convert_encoding($str, $to_encoding, $from_encoding, $default_charset)
 {
   // Allows mbstring functions only with iso-8859-*, utf-8 and 
@@ -214,4 +222,4 @@ function decodeBASE64($s) {
 	return $d;
 }
 
-?>
+?>

functions/index.php

@@ -11,8 +11,11 @@
  * the person is logged or not.
  *
  * $Id$
+ * @package squirrelmail
  */
 
+/** Redirect back to the login page
+ * @ignore */
 header("Location:../index.php");
 
 /* pretty impressive huh? */

functions/mailbox_display.php

@@ -10,8 +10,10 @@
  * table row that has sender, date, subject, etc...
  *
  * $Id$
+ * @package squirrelmail
  */
 
+/** The standard includes.. */
 require_once(SM_PATH . 'functions/strings.php');
 require_once(SM_PATH . 'functions/html.php');
 require_once(SM_PATH . 'class/html.class.php');
@@ -19,11 +21,14 @@ require_once(SM_PATH . 'functions/imap_mailbox.php');
 require_once(SM_PATH . 'functions/imap_messages.php');
 require_once(SM_PATH . 'functions/mime.php');
 
-/* Constants:
- *   PG_SEL_MAX:   default value for page_selector_max
+/**
+ * default value for page_selector_max
  */
 define('PG_SEL_MAX', 10);
 
+/**
+ * @param mixed $start UNDOCUMENTED
+ */
 function elapsed($start)
 {
    $end = microtime();

functions/mime.php

@@ -10,8 +10,10 @@
  * messages.
  *
  * $Id$
+ * @package squirrelmail
  */
 
+/** The typical includes... */
 require_once(SM_PATH . 'functions/imap.php');
 require_once(SM_PATH . 'functions/attachment_common.php');
 
@@ -19,11 +21,13 @@ require_once(SM_PATH . 'functions/attachment_common.php');
 /* MIME DECODING                                                              */
 /* -------------------------------------------------------------------------- */
 
-/* This function gets the structure of a message and stores it in the "message" class.
+/**
+ * Get the MIME structure
+ * 
+ * This function gets the structure of a message and stores it in the "message" class.
  * It will return this object for use with all relevant header information and
  * fully parsed into the standard "message" object format.
  */
-
 function mime_structure ($bodystructure, $flags=array()) {
 
     /* Isolate the body structure and remove beginning and end parenthesis. */
@@ -1958,4 +1962,4 @@ function magicHTML($body, $id, $message, $mailbox = 'INBOX') {
      }
  }
 
-?>
+?>

functions/options.php

@@ -9,6 +9,7 @@
  * Functions needed to display the options pages.
  *
  * $Id$
+ * @package squirrelmail
  */
 
 /**********************************************/

functions/page_header.php

@@ -9,14 +9,18 @@
  * Prints the page header (duh)
  *
  * $Id$
+ * @package squirrelmail
  */
 
+/** Include required files from SM */
 require_once(SM_PATH . 'functions/strings.php');
 require_once(SM_PATH . 'functions/html.php');
 require_once(SM_PATH . 'functions/imap_mailbox.php');
 require_once(SM_PATH . 'functions/global.php');
 
-/* Always set up the language before calling these functions */
+/**
+ * Always set up the language before calling these functions
+ */
 function displayHtmlHeader( $title = 'SquirrelMail', $xtra = '', $do_hook = TRUE ) {
     global $squirrelmail_language;
 

functions/plugin.php

@@ -11,14 +11,20 @@
  * Documentation on how to write plugins might show up some time.
  *
  * $Id$
+ * @package squirrelmail
  */
 
+/** Everything needs global.. */
 require_once(SM_PATH . 'functions/global.php');
 
 global $squirrelmail_plugin_hooks;
 $squirrelmail_plugin_hooks = array();
 
-/* This function adds a plugin. */
+/**
+ * This function adds a plugin.
+ * @param string $name Internal plugin name (ie. delete_move_next)
+ * @return void
+ */
 function use_plugin ($name) {
     if (file_exists(SM_PATH . "plugins/$name/setup.php")) {
         include_once(SM_PATH . "plugins/$name/setup.php");
@@ -29,7 +35,11 @@ function use_plugin ($name) {
     }
 }
 
-/* This function executes a hook. */
+/**
+ * This function executes a hook.
+ * @param string $name Name of hook to fire
+ * @return mixed $data
+ */
 function do_hook ($name) {
     global $squirrelmail_plugin_hooks;
     $data = func_get_args();

functions/prefs.php

@@ -9,8 +9,10 @@
  * This contains functions for manipulating user preferences
  *
  * $Id$
+ * @package squirrelmail
  */
 
+/** Include global.php */
 require_once(SM_PATH . 'functions/global.php');
 
 sqgetGlobalVar('prefs_cache', $prefs_cache, SQ_SESSION );

functions/strings.php

@@ -10,6 +10,7 @@
  * used by the rest of the Squirrelmail code.
  *
  * $Id$
+ * @package squirrelmail
  */
 
 /**

functions/tree.php

@@ -10,13 +10,13 @@
  * used by the rest of the Squirrelmail code.
  *
  * $Id$
+ * @package squirrelmail
  */
 
+/** Clearly, this needs the IMAP functions.. */
 require_once(SM_PATH . 'functions/imap.php');
 
 /**
- * findParentForChild
- *
  * Recursive function to find the correct parent for a new node
  */
 

functions/url_parser.php

@@ -10,8 +10,12 @@
  * used by the rest of the Squirrelmail code.
  *
  * $Id$
+ * @package squirrelmail
  */
 
+/**
+ * Undocumented - complain, then patch.
+ */
 function replaceBlock (&$in, $replace, $start, $end) {
     $begin = substr($in,0,$start);
     $end   = substr($in,$end,strlen($in)-$end);