From d6c32258c05219670ab3b4ae2d460d844ea9a247 Mon Sep 17 00:00:00 2001 From: tassium Date: Tue, 28 Oct 2003 21:27:47 +0000 Subject: [PATCH] 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 ;) git-svn-id: https://svn.code.sf.net/p/squirrelmail/code/trunk/squirrelmail@6040 7612ce4b-ef26-0410-bec9-ea0150e637f0 --- functions/abook_database.php | 10 +++++++-- functions/abook_global_file.php | 7 ++++++- functions/abook_ldap_server.php | 5 +++++ functions/abook_local_file.php | 6 +++++- functions/addressbook.php | 5 +++-- functions/attachment_common.php | 4 ++++ functions/auth.php | 3 ++- functions/constants.php | 2 ++ functions/date.php | 4 +++- functions/db_prefs.php | 10 ++++++++- functions/decode/big5.php | 12 ++++++++--- functions/decode/cp10000.php | 11 ++++++++-- functions/decode/cp10006.php | 11 ++++++++-- functions/decode/cp10007.php | 12 ++++++++--- functions/decode/cp10017.php | 11 ++++++++-- functions/decode/cp10029.php | 11 ++++++++-- functions/decode/cp10079.php | 11 ++++++++-- functions/decode/cp10081.php | 11 ++++++++-- functions/decode/cp1250.php | 12 ++++++++--- functions/decode/cp1251.php | 12 ++++++++--- functions/decode/cp1252.php | 13 +++++++++--- functions/decode/cp1253.php | 12 ++++++++--- functions/decode/cp1254.php | 12 ++++++++--- functions/decode/cp1255.php | 12 ++++++++--- functions/decode/cp1256.php | 12 ++++++++--- functions/decode/cp1257.php | 12 ++++++++--- functions/decode/cp1258.php | 12 ++++++++--- functions/decode/cp855.php | 11 ++++++++-- functions/decode/cp866.php | 10 +++++++-- functions/decode/gb2312.php | 14 ++++++++++--- functions/decode/iso-ir-111.php | 12 +++++++++-- functions/decode/iso8859-1.php | 13 +++++++++--- functions/decode/iso8859-10.php | 13 +++++++++--- functions/decode/iso8859-11.php | 13 +++++++++--- functions/decode/iso8859-13.php | 13 +++++++++--- functions/decode/iso8859-14.php | 13 +++++++++--- functions/decode/iso8859-15.php | 13 +++++++++--- functions/decode/iso8859-16.php | 13 +++++++++--- functions/decode/iso8859-2.php | 13 +++++++++--- functions/decode/iso8859-3.php | 13 +++++++++--- functions/decode/iso8859-4.php | 13 +++++++++--- functions/decode/iso8859-5.php | 13 +++++++++--- functions/decode/iso8859-6.php | 13 +++++++++--- functions/decode/iso8859-7.php | 13 +++++++++--- functions/decode/iso8859-8.php | 13 +++++++++--- functions/decode/iso8859-9.php | 13 +++++++++--- functions/decode/koi8-r.php | 11 ++++++++-- functions/decode/koi8-u.php | 12 +++++++++-- functions/decode/tis620.php | 12 +++++++++-- functions/decode/utf-8.php | 12 +++++++++-- functions/display_messages.php | 3 ++- functions/file_prefs.php | 3 ++- functions/gettext.php | 2 ++ functions/global.php | 12 ++++++----- functions/html.php | 13 +++++++++++- functions/i18n.php | 10 ++++++++- functions/identity.php | 4 +++- functions/imap.php | 2 ++ functions/imap_asearch.php | 8 ++++--- functions/imap_general.php | 2 ++ functions/imap_mailbox.php | 20 +++++++++++------- functions/imap_messages.php | 37 ++++++++++++++++++++++++++------- functions/imap_search.php | 4 ++++ functions/imap_utf7_local.php | 10 ++++++++- functions/index.php | 3 +++ functions/mailbox_display.php | 9 ++++++-- functions/mime.php | 10 ++++++--- functions/options.php | 1 + functions/page_header.php | 6 +++++- functions/plugin.php | 14 +++++++++++-- functions/prefs.php | 2 ++ functions/strings.php | 1 + functions/tree.php | 4 ++-- functions/url_parser.php | 4 ++++ 74 files changed, 574 insertions(+), 154 deletions(-) diff --git a/functions/abook_database.php b/functions/abook_database.php index aad28713..0a2b09b6 100644 --- a/functions/abook_database.php +++ b/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'; diff --git a/functions/abook_global_file.php b/functions/abook_global_file.php index 95e2dd39..93fd0f89 100644 --- a/functions/abook_global_file.php +++ b/functions/abook_global_file.php @@ -1,7 +1,7 @@ \ No newline at end of file +?> diff --git a/functions/addressbook.php b/functions/addressbook.php index a6f916b4..dcafc36a 100644 --- a/functions/addressbook.php +++ b/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 */ diff --git a/functions/attachment_common.php b/functions/attachment_common.php index ad36120b..2f6e9b05 100644 --- a/functions/attachment_common.php +++ b/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; diff --git a/functions/auth.php b/functions/auth.php index 85eb8ff3..6f7a872b 100644 --- a/functions/auth.php +++ b/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'; diff --git a/functions/constants.php b/functions/constants.php index 00f771ed..263ba72e 100644 --- a/functions/constants.php +++ b/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 */ /**************************************************************/ diff --git a/functions/date.php b/functions/date.php index 8edb856c..1c894d22 100644 --- a/functions/date.php +++ b/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) { diff --git a/functions/db_prefs.php b/functions/db_prefs.php index a973f363..71f372a8 100644 --- a/functions/db_prefs.php +++ b/functions/db_prefs.php @@ -1,6 +1,6 @@ \ No newline at end of file +?> diff --git a/functions/decode/cp10000.php b/functions/decode/cp10000.php index 4da2ba4b..95c53980 100644 --- a/functions/decode/cp10000.php +++ b/functions/decode/cp10000.php @@ -1,5 +1,5 @@ * K.D. Chang + * @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; } -?> \ No newline at end of file +?> diff --git a/functions/decode/cp10006.php b/functions/decode/cp10006.php index b7d9f7d7..ec5e7af7 100644 --- a/functions/decode/cp10006.php +++ b/functions/decode/cp10006.php @@ -1,5 +1,5 @@ * K.D. Chang + * @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; } -?> \ No newline at end of file +?> diff --git a/functions/decode/cp10007.php b/functions/decode/cp10007.php index 2e288c4e..0794efd3 100644 --- a/functions/decode/cp10007.php +++ b/functions/decode/cp10007.php @@ -1,5 +1,5 @@ * K.D. Chang - * + * @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; } -?> \ No newline at end of file +?> diff --git a/functions/decode/cp10017.php b/functions/decode/cp10017.php index 77c63876..57d6e55a 100644 --- a/functions/decode/cp10017.php +++ b/functions/decode/cp10017.php @@ -1,5 +1,5 @@ \ No newline at end of file +?> diff --git a/functions/decode/cp10029.php b/functions/decode/cp10029.php index f7f45ecb..cd06b688 100644 --- a/functions/decode/cp10029.php +++ b/functions/decode/cp10029.php @@ -1,5 +1,5 @@ * K.D. Chang + * @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; } -?> \ No newline at end of file +?> diff --git a/functions/decode/cp10079.php b/functions/decode/cp10079.php index 212cd36c..5853ddb3 100644 --- a/functions/decode/cp10079.php +++ b/functions/decode/cp10079.php @@ -1,5 +1,5 @@ * K.D. Chang + * @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; } -?> \ No newline at end of file +?> diff --git a/functions/decode/cp10081.php b/functions/decode/cp10081.php index fc892c0c..ec0d3de7 100644 --- a/functions/decode/cp10081.php +++ b/functions/decode/cp10081.php @@ -1,5 +1,5 @@ * K.D. Chang + * @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; } -?> \ No newline at end of file +?> diff --git a/functions/decode/cp1250.php b/functions/decode/cp1250.php index 2b7369dd..a5ca5b82 100644 --- a/functions/decode/cp1250.php +++ b/functions/decode/cp1250.php @@ -1,5 +1,5 @@ \ No newline at end of file +?> diff --git a/functions/decode/cp1251.php b/functions/decode/cp1251.php index 6ba0ca07..91763f84 100644 --- a/functions/decode/cp1251.php +++ b/functions/decode/cp1251.php @@ -1,5 +1,5 @@ \ No newline at end of file +?> diff --git a/functions/decode/cp1252.php b/functions/decode/cp1252.php index a62b2482..ad0d19ed 100644 --- a/functions/decode/cp1252.php +++ b/functions/decode/cp1252.php @@ -1,5 +1,5 @@ \ No newline at end of file +?> diff --git a/functions/decode/cp1253.php b/functions/decode/cp1253.php index 268ef2c6..02961255 100644 --- a/functions/decode/cp1253.php +++ b/functions/decode/cp1253.php @@ -1,5 +1,5 @@ \ No newline at end of file +?> diff --git a/functions/decode/cp1254.php b/functions/decode/cp1254.php index 08f1c0b9..51b605c9 100644 --- a/functions/decode/cp1254.php +++ b/functions/decode/cp1254.php @@ -1,5 +1,5 @@ \ No newline at end of file +?> diff --git a/functions/decode/cp1255.php b/functions/decode/cp1255.php index ad54e75e..1f92952d 100644 --- a/functions/decode/cp1255.php +++ b/functions/decode/cp1255.php @@ -1,5 +1,5 @@ \ No newline at end of file +?> diff --git a/functions/decode/cp1256.php b/functions/decode/cp1256.php index 8effc807..bc1259a5 100644 --- a/functions/decode/cp1256.php +++ b/functions/decode/cp1256.php @@ -1,5 +1,5 @@ \ No newline at end of file +?> diff --git a/functions/decode/cp1257.php b/functions/decode/cp1257.php index 8a60f6bf..d3f9eb63 100644 --- a/functions/decode/cp1257.php +++ b/functions/decode/cp1257.php @@ -1,5 +1,5 @@ \ No newline at end of file +?> diff --git a/functions/decode/cp1258.php b/functions/decode/cp1258.php index 431ad41d..860ca390 100644 --- a/functions/decode/cp1258.php +++ b/functions/decode/cp1258.php @@ -1,5 +1,5 @@ \ No newline at end of file +?> diff --git a/functions/decode/cp855.php b/functions/decode/cp855.php index e8e219e8..45b968ae 100644 --- a/functions/decode/cp855.php +++ b/functions/decode/cp855.php @@ -1,5 +1,5 @@ * K.D. Chang + * @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; } -?> \ No newline at end of file +?> diff --git a/functions/decode/cp866.php b/functions/decode/cp866.php index 63e221bd..ea4632b2 100644 --- a/functions/decode/cp866.php +++ b/functions/decode/cp866.php @@ -1,5 +1,5 @@ K.D. Chang 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; diff --git a/functions/decode/gb2312.php b/functions/decode/gb2312.php index 38be0af3..22e9f3df 100644 --- a/functions/decode/gb2312.php +++ b/functions/decode/gb2312.php @@ -1,5 +1,5 @@ \ No newline at end of file +?> diff --git a/functions/decode/iso-ir-111.php b/functions/decode/iso-ir-111.php index bd10ca04..cee5069c 100644 --- a/functions/decode/iso-ir-111.php +++ b/functions/decode/iso-ir-111.php @@ -1,5 +1,5 @@ \ No newline at end of file +?> diff --git a/functions/decode/iso8859-1.php b/functions/decode/iso8859-1.php index 66cff92f..5bbe7430 100644 --- a/functions/decode/iso8859-1.php +++ b/functions/decode/iso8859-1.php @@ -1,5 +1,5 @@ \ No newline at end of file +?> diff --git a/functions/decode/iso8859-10.php b/functions/decode/iso8859-10.php index 8cdb0deb..655b1247 100644 --- a/functions/decode/iso8859-10.php +++ b/functions/decode/iso8859-10.php @@ -1,5 +1,5 @@ \ No newline at end of file +?> diff --git a/functions/decode/iso8859-11.php b/functions/decode/iso8859-11.php index 044bc175..7d34f72d 100644 --- a/functions/decode/iso8859-11.php +++ b/functions/decode/iso8859-11.php @@ -1,5 +1,5 @@ \ No newline at end of file +?> diff --git a/functions/decode/iso8859-13.php b/functions/decode/iso8859-13.php index 8b85a6dd..475a5f06 100644 --- a/functions/decode/iso8859-13.php +++ b/functions/decode/iso8859-13.php @@ -1,5 +1,5 @@ \ No newline at end of file +?> diff --git a/functions/decode/iso8859-14.php b/functions/decode/iso8859-14.php index 16ecca9f..2203fc07 100644 --- a/functions/decode/iso8859-14.php +++ b/functions/decode/iso8859-14.php @@ -1,5 +1,5 @@ \ No newline at end of file +?> diff --git a/functions/decode/iso8859-15.php b/functions/decode/iso8859-15.php index 35a665ea..af83a572 100644 --- a/functions/decode/iso8859-15.php +++ b/functions/decode/iso8859-15.php @@ -1,5 +1,5 @@ \ No newline at end of file +?> diff --git a/functions/decode/iso8859-16.php b/functions/decode/iso8859-16.php index 90c2396c..f5e96919 100644 --- a/functions/decode/iso8859-16.php +++ b/functions/decode/iso8859-16.php @@ -1,5 +1,5 @@ \ No newline at end of file +?> diff --git a/functions/decode/iso8859-2.php b/functions/decode/iso8859-2.php index c4e03698..1dd5c6ad 100644 --- a/functions/decode/iso8859-2.php +++ b/functions/decode/iso8859-2.php @@ -1,5 +1,5 @@ \ No newline at end of file +?> diff --git a/functions/decode/iso8859-3.php b/functions/decode/iso8859-3.php index 8893795f..eb408910 100644 --- a/functions/decode/iso8859-3.php +++ b/functions/decode/iso8859-3.php @@ -1,5 +1,5 @@ \ No newline at end of file +?> diff --git a/functions/decode/iso8859-4.php b/functions/decode/iso8859-4.php index f93636b3..e2b0247e 100644 --- a/functions/decode/iso8859-4.php +++ b/functions/decode/iso8859-4.php @@ -1,5 +1,5 @@ \ No newline at end of file +?> diff --git a/functions/decode/iso8859-5.php b/functions/decode/iso8859-5.php index 5d970347..7c3ae2b3 100644 --- a/functions/decode/iso8859-5.php +++ b/functions/decode/iso8859-5.php @@ -1,5 +1,5 @@ \ No newline at end of file +?> diff --git a/functions/decode/iso8859-6.php b/functions/decode/iso8859-6.php index e90053a3..c67dbf27 100644 --- a/functions/decode/iso8859-6.php +++ b/functions/decode/iso8859-6.php @@ -1,5 +1,5 @@ \ No newline at end of file +?> diff --git a/functions/decode/iso8859-7.php b/functions/decode/iso8859-7.php index 850fef4b..e9d90fc5 100644 --- a/functions/decode/iso8859-7.php +++ b/functions/decode/iso8859-7.php @@ -1,5 +1,5 @@ \ No newline at end of file +?> diff --git a/functions/decode/iso8859-8.php b/functions/decode/iso8859-8.php index 0f3d0b8b..439d4b00 100644 --- a/functions/decode/iso8859-8.php +++ b/functions/decode/iso8859-8.php @@ -1,5 +1,5 @@ \ No newline at end of file +?> diff --git a/functions/decode/iso8859-9.php b/functions/decode/iso8859-9.php index 6d6a52de..41b41b35 100644 --- a/functions/decode/iso8859-9.php +++ b/functions/decode/iso8859-9.php @@ -1,5 +1,5 @@ \ No newline at end of file +?> diff --git a/functions/decode/koi8-r.php b/functions/decode/koi8-r.php index fee1ab9a..84628d81 100644 --- a/functions/decode/koi8-r.php +++ b/functions/decode/koi8-r.php @@ -1,5 +1,5 @@ \ No newline at end of file +?> diff --git a/functions/decode/koi8-u.php b/functions/decode/koi8-u.php index 8b5bb0b9..f01ce9e5 100644 --- a/functions/decode/koi8-u.php +++ b/functions/decode/koi8-u.php @@ -1,5 +1,5 @@ \ No newline at end of file +?> diff --git a/functions/decode/tis620.php b/functions/decode/tis620.php index 8e1b4d71..53183175 100644 --- a/functions/decode/tis620.php +++ b/functions/decode/tis620.php @@ -1,5 +1,5 @@ \ No newline at end of file +?> diff --git a/functions/decode/utf-8.php b/functions/decode/utf-8.php index b5baec64..72f2a160 100644 --- a/functions/decode/utf-8.php +++ b/functions/decode/utf-8.php @@ -1,5 +1,5 @@ \ No newline at end of file +?> diff --git a/functions/display_messages.php b/functions/display_messages.php index f035a201..0e5831ad 100644 --- a/functions/display_messages.php +++ b/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; diff --git a/functions/file_prefs.php b/functions/file_prefs.php index f21e89f7..b579bdd4 100644 --- a/functions/file_prefs.php +++ b/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'); /** diff --git a/functions/gettext.php b/functions/gettext.php index 924904b9..fa74b24f 100644 --- a/functions/gettext.php +++ b/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, diff --git a/functions/global.php b/functions/global.php index d4e5c535..6344ddcb 100644 --- a/functions/global.php +++ b/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'); diff --git a/functions/html.php b/functions/html.php index 3a6c4142..b82dc5ee 100644 --- a/functions/html.php +++ b/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 diff --git a/functions/i18n.php b/functions/i18n.php index 03c48554..3d99ed06 100644 --- a/functions/i18n.php +++ b/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; diff --git a/functions/identity.php b/functions/identity.php index 6cece743..4b22f542 100644 --- a/functions/identity.php +++ b/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() { diff --git a/functions/imap.php b/functions/imap.php index 3abe4a48..b4a9bc93 100644 --- a/functions/imap.php +++ b/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'); diff --git a/functions/imap_asearch.php b/functions/imap_asearch.php index df6209cc..f3dc5676 100644 --- a/functions/imap_asearch.php +++ b/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; } -?> \ No newline at end of file +?> diff --git a/functions/imap_general.php b/functions/imap_general.php index adad9349..ddbb9fdd 100755 --- a/functions/imap_general.php +++ b/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'); diff --git a/functions/imap_mailbox.php b/functions/imap_mailbox.php index 5d8a1a6a..929276ac 100755 --- a/functions/imap_mailbox.php +++ b/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 { diff --git a/functions/imap_messages.php b/functions/imap_messages.php index a01ca615..f3e1023c 100755 --- a/functions/imap_messages.php +++ b/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); diff --git a/functions/imap_search.php b/functions/imap_search.php index 38832fc1..5028a810 100644 --- a/functions/imap_search.php +++ b/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'); diff --git a/functions/imap_utf7_local.php b/functions/imap_utf7_local.php index 3435f48f..9a15db9b 100644 --- a/functions/imap_utf7_local.php +++ b/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; } -?> \ No newline at end of file +?> diff --git a/functions/index.php b/functions/index.php index 269f8987..b8c59e84 100644 --- a/functions/index.php +++ b/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? */ diff --git a/functions/mailbox_display.php b/functions/mailbox_display.php index aad15500..aa15493b 100644 --- a/functions/mailbox_display.php +++ b/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(); diff --git a/functions/mime.php b/functions/mime.php index 0d6ff091..f642133e 100644 --- a/functions/mime.php +++ b/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') { } } -?> \ No newline at end of file +?> diff --git a/functions/options.php b/functions/options.php index bdd5df13..b516e45d 100644 --- a/functions/options.php +++ b/functions/options.php @@ -9,6 +9,7 @@ * Functions needed to display the options pages. * * $Id$ + * @package squirrelmail */ /**********************************************/ diff --git a/functions/page_header.php b/functions/page_header.php index bc63eced..ef044bcb 100644 --- a/functions/page_header.php +++ b/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; diff --git a/functions/plugin.php b/functions/plugin.php index 9c70edd1..56315dc4 100644 --- a/functions/plugin.php +++ b/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(); diff --git a/functions/prefs.php b/functions/prefs.php index 10ea919a..8521f39b 100644 --- a/functions/prefs.php +++ b/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 ); diff --git a/functions/strings.php b/functions/strings.php index 9e137cab..8f2cfa7c 100644 --- a/functions/strings.php +++ b/functions/strings.php @@ -10,6 +10,7 @@ * used by the rest of the Squirrelmail code. * * $Id$ + * @package squirrelmail */ /** diff --git a/functions/tree.php b/functions/tree.php index 86392922..c35bc0e2 100644 --- a/functions/tree.php +++ b/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 */ diff --git a/functions/url_parser.php b/functions/url_parser.php index 20b1fdae..02181fbe 100644 --- a/functions/url_parser.php +++ b/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); -- 2.25.1