phpdocumentor preparation and a few corrections to earlier phpdocumentor work

functions/abook_local_file.php

@@ -24,6 +24,7 @@
 
 /**
  * Store the addressbook in a local file
+ * @package squirrelmail
  */
 class abook_local_file extends addressbook_backend {
     var $btype = 'local';

functions/addressbook.php

@@ -123,10 +123,10 @@ function addressbook_cmp($a,$b) {
 }
 
 
-/*
+/**
  * This is the main address book class that connect all the
  * backends and provide services to the functions above.
- *
+ * @package squirrelmail
  */
 
 class AddressBook {
@@ -462,8 +462,9 @@ class AddressBook {
     
 } /* End of class Addressbook */
 
-/*
+/**
  * Generic backend that all other backends extend
+ * @package squirrelmail
  */
 class addressbook_backend {
 

functions/options.php

@@ -53,6 +53,7 @@ define('SMOPT_SAVE_NOOP', 'save_option_noop');
  * Also, I'd like to ask that people leave this alone (mostly :) until
  * I get it a little further along. That should only be a day or two or
  * three. I will remove this message when it is ready for primetime usage.
+ * @package squirrelmail
  */
 class SquirrelOption {
     /* The basic stuff. */

src/addrbook_popup.php

@@ -9,12 +9,13 @@
  * Frameset for the JavaScript version of the address book.
  *
  * $Id$
+ * @package squirrelmail
  */
 
-/* Path for SquirrelMail required files. */
+/** Path for SquirrelMail required files. */
 define('SM_PATH','../');
 
-/* SquirrelMail required files. */
+/** SquirrelMail required files. */
 require_once(SM_PATH . 'include/validate.php');
 require_once(SM_PATH . 'functions/addressbook.php');
    

src/addrbook_search.php

@@ -12,19 +12,22 @@
  *       addrbook_search_html.html -- If you change one,
  *       change the other one too!
  *
- * $Id$
+ * $Id$ 
+ * @package squirrelmail
  */
 
-/* Path for SquirrelMail required files. */
+/**
+ * Path for SquirrelMail required files.
+ */
 define('SM_PATH','../');
 
-/* SquirrelMail required files. */
+/** SquirrelMail required files. */
 require_once(SM_PATH . 'include/validate.php');
 require_once(SM_PATH . 'functions/strings.php');
 require_once(SM_PATH . 'functions/global.php');
 require_once(SM_PATH . 'functions/html.php');
 
-/* lets get the global vars we may need */
+/** lets get the global vars we may need */
 sqgetGlobalVar('key',       $key,           SQ_COOKIE);
 sqgetGlobalVar('username',  $username,      SQ_SESSION);
 sqgetGlobalVar('onetimepad',$onetimepad,    SQ_SESSION);
@@ -35,7 +38,10 @@ sqgetGlobalVar('query',   $query,   SQ_POST);
 sqgetGlobalVar('listall', $listall, SQ_POST);
 sqgetGlobalVar('backend', $backend, SQ_POST);
 
-/* Function to include JavaScript code */
+/**
+ * Function to include JavaScript code
+ * @return void
+ */
 function insert_javascript() {
     ?>
     <SCRIPT LANGUAGE="Javascript"><!--
@@ -101,7 +107,12 @@ function insert_javascript() {
 } /* End of included JavaScript */
 
 
-/* List search results */
+/**
+ * List search results
+ * @param array $res Array of search results
+ * @param bool $includesource [Default=true]
+ * @return void
+ */
 function display_result($res, $includesource = true) {
     global $color;
         

src/addrbook_search_html.php

@@ -11,14 +11,15 @@
  * This file is included from compose.php
  *
  * $Id$
+ * @package squirrelmail
  */
 
-/* Path for SquirrelMail required files. */
+/** Path for SquirrelMail required files. */
 if (! defined('SM_PATH') ) {
 	define('SM_PATH','../');
 }
 
-/* SquirrelMail required files. */
+/** SquirrelMail required files. */
 require_once(SM_PATH . 'include/validate.php');
 require_once(SM_PATH . 'functions/global.php');
 require_once(SM_PATH . 'functions/date.php');
@@ -34,7 +35,9 @@ sqgetGlobalVar('addrquery', $addrquery, SQ_POST);
 sqgetGlobalVar('listall',   $listall,   SQ_POST);
 sqgetGlobalVar('backend',   $backend,   SQ_POST);
 
-/* Insert hidden data */
+/**
+ * Insert hidden data
+ */
 function addr_insert_hidden() {
     global $body, $subject, $send_to, $send_to_cc, $send_to_bcc, $mailbox,
            $identity, $session;
@@ -61,7 +64,11 @@ function addr_insert_hidden() {
    }
 
 
-/* List search results */
+/**
+ * List search results
+ * @param array $res Array containing results of search
+ * @param bool $includesource UNDOCUMENTED [Default=true]
+ */
 function addr_display_result($res, $includesource = true) {
     global $color, $javascript_on, $PHP_SELF, $squirrelmail_language;
 

src/addressbook.php

@@ -9,12 +9,13 @@
  * Manage personal address book.
  *
  * $Id$
+ * @package squirrelmail
  */
 
-/* Path for SquirrelMail required files. */
+/** Path for SquirrelMail required files. */
 define('SM_PATH','../');
 
-/* SquirrelMail required files. */
+/** SquirrelMail required files. */
 require_once(SM_PATH . 'include/validate.php');
 require_once(SM_PATH . 'functions/global.php');
 require_once(SM_PATH . 'functions/display_messages.php');
@@ -22,7 +23,7 @@ require_once(SM_PATH . 'functions/addressbook.php');
 require_once(SM_PATH . 'functions/strings.php');
 require_once(SM_PATH . 'functions/html.php');
 
-/* lets get the global vars we may need */
+/** lets get the global vars we may need */
 sqgetGlobalVar('key',       $key,           SQ_COOKIE);
 
 sqgetGlobalVar('username',  $username,      SQ_SESSION);
@@ -39,7 +40,15 @@ sqgetGlobalVar('oldnick',   $oldnick,   SQ_POST);
 sqgetGlobalVar('backend',   $backend,   SQ_POST);
 sqgetGlobalVar('doedit',    $doedit,    SQ_POST); 
 
-/* Make an input field */
+/**
+ * Make an input field
+ * @param string $label
+ * @param string $field
+ * @param string $name
+ * @param string $size
+ * @param array $values
+ * @param string $add
+ */
 function adressbook_inp_field($label, $field, $name, $size, $values, $add) {
     global $color;
     $td_str = '<INPUT NAME="' . $name . '[' . $field . ']" SIZE="' . $size . '" VALUE="';
@@ -54,7 +63,9 @@ function adressbook_inp_field($label, $field, $name, $size, $values, $add) {
     . "\n";
 }
 
-/* Output form to add and modify address data */
+/**
+ * Output form to add and modify address data
+ */
 function address_form($name, $submittext, $values = array()) {
     global $color, $squirrelmail_language;
     

src/compose.php

@@ -15,9 +15,10 @@
  *    - Save As Draft
  *
  * $Id$
+ * @package squirrelmail
  */
 
-/* Path for SquirrelMail required files. */
+/** Path for SquirrelMail required files. */
 define('SM_PATH','../');
 
 /* SquirrelMail required files. */

src/delete_message.php

@@ -9,9 +9,10 @@
  * Deletes a meesage from the IMAP server
  *
  * $Id$
+ * @package squirrelmail
  */
 
-/* Path for SquirrelMail required files. */
+/** Path for SquirrelMail required files. */
 define('SM_PATH','../');
 
 /* SquirrelMail required files. */

src/empty_trash.php

@@ -10,9 +10,10 @@
  * deleting subfolders.
  *
  * $Id$
+ * @package squirrelmail
  */
 
-/* Path for SquirrelMail required files. */
+/** Path for SquirrelMail required files. */
 define('SM_PATH','../');
 
 /* SquirrelMail required files. */

src/folders.php

@@ -11,9 +11,10 @@
  * Folders.
  *
  * $Id$
+ * @package squirrelmail
  */
 
-/* Path for SquirrelMail required files. */
+/** Path for SquirrelMail required files. */
 define('SM_PATH','../');
 
 /* SquirrelMail required files. */

src/folders_create.php

@@ -10,9 +10,10 @@
  * Called from folders.php
  *
  * $Id$
+ * @package squirrelmail
  */
 
-/* Path for SquirrelMail required files. */
+/** Path for SquirrelMail required files. */
 define('SM_PATH','../');
 
 /* SquirrelMail required files. */

src/folders_delete.php

@@ -10,9 +10,10 @@
  * Called from the folders.php
  *
  * $Id$
+ * @package squirrelmail
  */
 
-/* Path for SquirrelMail required files. */
+/** Path for SquirrelMail required files. */
 define('SM_PATH','../');
 
 /* SquirrelMail required files. */

src/folders_rename_do.php

@@ -10,9 +10,10 @@
  * Called from the folders.php
  *
  * $Id$
+ * @package squirrelmail
  */
 
-/* Path for SquirrelMail required files. */
+/** Path for SquirrelMail required files. */
 define('SM_PATH','../');
 
 /* SquirrelMail required files. */

src/folders_rename_getname.php

@@ -10,9 +10,10 @@
  * Called from folders.php
  *
  * $Id$
+ * @package squirrelmail
  */
 
-/* Path for SquirrelMail required files. */
+/** Path for SquirrelMail required files. */
 define('SM_PATH','../');
 
 /* SquirrelMail required files. */

src/folders_subscribe.php

@@ -10,9 +10,10 @@
  * Called from folders.php
  *
  * $Id$
+ * @package squirrelmail
  */
 
-/* Path for SquirrelMail required files. */
+/** Path for SquirrelMail required files. */
 define('SM_PATH','../');
 
 /* SquirrelMail required files. */

src/help.php

@@ -9,9 +9,10 @@
  * Displays help for the user
  *
  * $Id$
+ * @package squirrelmail
  */
 
-/* Path for SquirrelMail required files. */
+/** Path for SquirrelMail required files. */
 define('SM_PATH','../');
 
 /* SquirrelMail required files. */

src/image.php

@@ -9,9 +9,10 @@
  * This file shows an attached image
  *
  * $Id$
+ * @package squirrelmail
  */
 
-/* Path for SquirrelMail required files. */
+/** Path for SquirrelMail required files. */
 define('SM_PATH','../');
 
 /* SquirrelMail required files. */

src/index.php

@@ -11,6 +11,7 @@
  * the person is logged or not.
  *
  * $Id$
+ * @package squirrelmail
  */
 
 header("Location:../index.php");

src/left_main.php

@@ -10,9 +10,10 @@
  * available, and has cookie information.
  *
  * $Id$
+ * @package squirrelmail
  */
 
-/* Path for SquirrelMail required files. */
+/** Path for SquirrelMail required files. */
 define('SM_PATH','../');
 
 /* SquirrelMail required files. */
@@ -196,8 +197,7 @@ function create_collapse_link($boxnum) {
  * @param string $boxName name of the current mailbox
  * @param array $boxArray array for the current mailbox
  * @param $imapConnection current imap connection in use
- * @return array[0] unseen message string (for display)
- * @return array[1] unseen message count
+ * @return array unseen message string (for display), unseen message count
  */
 function create_unseen_string($boxName, $boxArray, $imapConnection, $unseen_type) {
     global $boxes, $unseen_type, $color, $unseen_cum;

src/login.php

@@ -10,9 +10,10 @@
  * cookies and find language.
  *
  * $Id$
+ * @package squirrelmail
  */
 
-/* Path for SquirrelMail required files. */
+/** Path for SquirrelMail required files. */
 define('SM_PATH','../');
 
 /* SquirrelMail required files. */
@@ -26,7 +27,7 @@ require_once(SM_PATH . 'functions/html.php');
 require_once(SM_PATH . 'functions/global.php');
 require_once(SM_PATH . 'functions/imap_general.php');
 
-/*
+/**
  * $squirrelmail_language is set by a cookie when the user selects
  * language and logs out
  */
@@ -49,6 +50,11 @@ sqsession_destroy();
  
 header('Pragma: no-cache');
 
+/**
+ * This detects if the IMAP server has logins disabled, and if so, 
+ * squelches the display of the login form and puts up a message
+ * explaining the situation.
+ */
 $imap = sqimap_create_stream($imapServerAddress, $imapPort, $use_imap_tls);
 $logindisabled = sqimap_capability($imap,'LOGINDISABLED');
 sqimap_logout($imap);

src/mailto.php

@@ -14,9 +14,10 @@
  * Use the following url to use mailto:
  * http://<your server>/<squirrelmail base dir>/src/mailto.php?emailaddress="%1"
  * see ../contrib/squirrelmail.mailto.reg for a Windows Registry file
+ * @package squirrelmail
  */
 
-/* Path for SquirrelMail required files. */
+/** Path for SquirrelMail required files. */
 define('SM_PATH','../');
 
 /* SquirrelMail required files. */

src/move_messages.php

@@ -9,9 +9,10 @@
  * Enables message moving between folders on the IMAP server.
  *
  * $Id$
+ * @package squirrelmail
  */
 
-/* Path for SquirrelMail required files. */
+/** Path for SquirrelMail required files. */
 define('SM_PATH','../');
 
 /* SquirrelMail required files. */

src/options.php

@@ -10,9 +10,10 @@
  * and config.php. Displays preferences as selected and other options.
  *
  * $Id$
+ * @package squirrelmail
  */
 
-/* Path for SquirrelMail required files. */
+/** Path for SquirrelMail required files. */
 define('SM_PATH','../');
 
 /* SquirrelMail required files. */

src/options_highlight.php

@@ -9,9 +9,10 @@
  * Displays message highlighting options
  *
  * $Id$
+ * @package squirrelmail
  */
 
-/* Path for SquirrelMail required files. */
+/** Path for SquirrelMail required files. */
 define('SM_PATH','../');
 
 /* SquirrelMail required files. */

src/options_identities.php

@@ -9,9 +9,10 @@
  * Display Identities Options
  *
  * $Id$
+ * @package squirrelmail
  */
 
-/* Path for SquirrelMail required files. */
+/** Path for SquirrelMail required files. */
 define('SM_PATH','../');
 
 /* SquirrelMail required files. */

src/options_order.php

@@ -9,9 +9,10 @@
  * Displays messagelist column order options
  *
  * $Id$
+ * @package squirrelmail
  */
 
-/* Path for SquirrelMail required files. */
+/** Path for SquirrelMail required files. */
 define('SM_PATH','../');
 
 /* SquirrelMail required files. */

src/printer_friendly_bottom.php

@@ -12,9 +12,10 @@
  * - this is the page that does all the work, really.
  *
  * $Id$
+ * @package squirrelmail
  */
 
-/* Path for SquirrelMail required files. */
+/** Path for SquirrelMail required files. */
 define('SM_PATH','../');
 
 /* SquirrelMail required files. */

src/printer_friendly_main.php

@@ -7,9 +7,10 @@
  * Licensed under the GNU GPL. For full terms see the file COPYING.
  *
  * $Id$
+ * @package squirrelmail
  */
 
-/* Path for SquirrelMail required files. */
+/** Path for SquirrelMail required files. */
 define('SM_PATH','../');
 
 /* SquirrelMail required files. */

src/printer_friendly_top.php

@@ -10,9 +10,10 @@
  * displays some javascript buttons for printing & closing
  *
  * $Id$
+ * @package squirrelmail
  */
 
-/* Path for SquirrelMail required files. */
+/** Path for SquirrelMail required files. */
 define('SM_PATH','../');
 
 /* SquirrelMail required files. */

src/read_body.php

@@ -10,9 +10,10 @@
  * the resulting emails in the right frame.
  *
  * $Id$
+ * @package squirrelmail
  */
 
-/* Path for SquirrelMail required files. */
+/** Path for SquirrelMail required files. */
 define('SM_PATH','../');
 
 /* SquirrelMail required files. */

src/redirect.php

@@ -10,9 +10,10 @@
 * Prevents users from reposting their form data after a successful logout.
 *
 * $Id$
+* @package squirrelmail
 */
 
-/* Path for SquirrelMail required files. */
+/** Path for SquirrelMail required files. */
 define('SM_PATH','../');
 
 /* SquirrelMail required files. */

src/right_main.php

@@ -10,9 +10,10 @@
  * goes on in SquirrelMail.
  *
  * $Id$
+ * @package squirrelmail
  */
 
-/* Path for SquirrelMail required files. */
+/** Path for SquirrelMail required files. */
 define('SM_PATH','../');
 
 /* SquirrelMail required files. */

src/search.php

@@ -6,10 +6,11 @@
  * Copyright (c) 1999-2003 The SquirrelMail Project Team
  * Licensed under the GNU GPL. For full terms see the file COPYING.
  *
- * Originally by Alex Lemaresquier - Brainstorm - alex at brainstorm.fr
+ * @author Alex Lemaresquier - Brainstorm - alex at brainstorm.fr
+ * @package squirrelmail
  */
 
-/* Path for SquirrelMail required files. */
+/** Path for SquirrelMail required files. */
 define('SM_PATH','../');
 
 /* SquirrelMail required files. */
@@ -939,4 +940,4 @@ do_hook('search_bottom');
 sqimap_logout($imapConnection);
 echo '</body></html>';
 
-?>
+?>

src/signout.php

@@ -9,9 +9,10 @@
  *  Cleans up after the user. Resets cookies and terminates session.
  *
  * $Id$
+ * @package squirrelmail
  */
 
-/* Path for SquirrelMail required files. */
+/** Path for SquirrelMail required files. */
 define('SM_PATH','../');
 
 /* SquirrelMail required files. */

src/vcard.php

@@ -9,9 +9,10 @@
  * This file shows an attched vcard
  *
  * $Id$
+ * @package squirrelmail
  */
 
-/* Path for SquirrelMail required files. */
+/** Path for SquirrelMail required files. */
 Define('SM_PATH','../');
 
 /* SquirrelMail required files. */

src/view_header.php

@@ -9,9 +9,10 @@
  * This is the code to view the message header.
  *
  * $Id$
+ * @package squirrelmail
  */
 
-/* Path for SquirrelMail required files. */
+/** Path for SquirrelMail required files. */
 define('SM_PATH','../');
 
 /* SquirrelMail required files. */

src/view_text.php

@@ -11,9 +11,10 @@
  * be very ashamed.
  *
  * $Id$
+ * @package squirrelmail
  */
 
-/* Path for SquirrelMail required files. */
+/** Path for SquirrelMail required files. */
 define('SM_PATH','../');
 
 /* SquirrelMail required files. */

src/webmail.php

@@ -11,9 +11,10 @@
  * this file will verify username and password.
  *
  * $Id$
+ * @package squirrelmail
  */
 
-/* Path for SquirrelMail required files. */
+/** Path for SquirrelMail required files. */
 define('SM_PATH','../');
 
 /* SquirrelMail required files. */