adding phpdoc blocks.

fixed unchecked used of create. According to the docs it is optional.

functions/abook_local_file.php

@@ -1,44 +1,54 @@
 <?php
-
 /**
  * abook_local_file.php
  *
  * Copyright (c) 1999-2004 The SquirrelMail Project Team
  * Licensed under the GNU GPL. For full terms see the file COPYING.
  *
- * Backend for addressbook as a pipe separated file
- *
- * An array with the following elements must be passed to
- * the class constructor (elements marked ? are optional):
- *
- *    filename  => path to addressbook file
- *  ? create    => if true: file is created if it does not exist.
- *  ? umask     => umask set before opening file.
- *
- * NOTE. This class should not be used directly. Use the
- *       "AddressBook" class instead.
- *
  * @version $Id$
  * @package squirrelmail
  * @subpackage addressbook
  */
 
 /**
- * Store the addressbook in a local file
+ * Backend for address book as a pipe separated file
+ *
+ * Stores the address book in a local file
+ *
+ * An array with the following elements must be passed to
+ * the class constructor (elements marked ? are optional):
+ *<pre>
+ *   filename  => path to addressbook file
+ * ? create    => if true: file is created if it does not exist.
+ * ? umask     => umask set before opening file.
+ * ? name      => name of address book
+ *</pre>
+ * NOTE. This class should not be used directly. Use the
+ *       "AddressBook" class instead.
  * @package squirrelmail
  */
 class abook_local_file extends addressbook_backend {
+    /** @var string backend type */
     var $btype = 'local';
+    /** @var string backend name */
     var $bname = 'local_file';
 
+    /** @var string file used to store data */
     var $filename   = '';
+    /** @var object file handle */
     var $filehandle = 0;
+    /** @var bool create file if it is not present */
     var $create     = false;
+    /** @var string umask of the file */
     var $umask;
 
     /* ========================== Private ======================= */
 
-    /* Constructor */
+    /**
+     * Constructor
+     * @param array $param backend options
+     * @return bool
+     */
     function abook_local_file($param) {
         $this->sname = _("Personal address book");
         $this->umask = Umask();
@@ -54,8 +64,8 @@ class abook_local_file extends addressbook_backend {
 
             $this->filename = $param['filename'];
 
-            if($param['create']) {
-                $this->create = true;
+            if(isset($param['create'])) {
+                $this->create = $param['create'];
             }
             if(isset($param['umask'])) {
                 $this->umask = $param['umask'];
@@ -70,10 +80,14 @@ class abook_local_file extends addressbook_backend {
         }
     }
 
-    /* Open the addressbook file and store the file pointer.
+    /**
+     * Open the addressbook file and store the file pointer.
      * Use $file as the file to open, or the class' own
      * filename property. If $param is empty and file is
-     * open, do nothing. */
+     * open, do nothing.
+     * @param bool $new is file already opened
+     * @return bool
+     */
     function open($new = false) {
         $this->error = '';
         $file   = $this->filename;
@@ -113,7 +127,7 @@ class abook_local_file extends addressbook_backend {
         return true;
     }
 
-    /* Close the file and forget the filehandle */
+    /** Close the file and forget the filehandle */
     function close() {
         @fclose($this->filehandle);
         $this->filehandle = 0;
@@ -121,7 +135,7 @@ class abook_local_file extends addressbook_backend {
         $this->writable   = false;
     }
 
-    /* Lock the datafile - try 20 times in 5 seconds */
+    /** Lock the datafile - try 20 times in 5 seconds */
     function lock() {
         for($i = 0 ; $i < 20 ; $i++) {
             if(flock($this->filehandle, 2 + 4))
@@ -132,13 +146,17 @@ class abook_local_file extends addressbook_backend {
         return false;
     }
 
-    /* Lock the datafile */
+    /** Unlock the datafile */
     function unlock() {
         return flock($this->filehandle, 3);
     }
 
-    /* Overwrite the file with data from $rows
-     * NOTE! Previous locks are broken by this function */
+    /**
+     * Overwrite the file with data from $rows
+     * NOTE! Previous locks are broken by this function
+     * @param array $rows new data
+     * @return bool
+     */
     function overwrite(&$rows) {
         $this->unlock();
         $newfh = @fopen($this->filename.'.tmp', 'w');
@@ -171,7 +189,11 @@ class abook_local_file extends addressbook_backend {
 
     /* ========================== Public ======================== */
 
-    /* Search the file */
+    /**
+     * Search the file
+     * @param string $expr search expression
+     * @return array search results
+     */
     function search($expr) {
 
         /* To be replaced by advanded search expression parsing */
@@ -205,7 +227,11 @@ class abook_local_file extends addressbook_backend {
         return $res;
     }
 
-    /* Lookup alias */
+    /**
+     * Lookup alias
+     * @param string $alias alias
+     * @return array search results
+     */
     function lookup($alias) {
         if(empty($alias)) {
             return array();
@@ -232,7 +258,10 @@ class abook_local_file extends addressbook_backend {
         return array();
     }
 
-    /* List all addresses */
+    /**
+     * List all addresses
+     * @return array list of all addresses
+     */
     function list_addr() {
         $res = array();
         $this->open();
@@ -251,7 +280,11 @@ class abook_local_file extends addressbook_backend {
         return $res;
     }
 
-    /* Add address */
+    /**
+     * Add address
+     * @param array $userdata new data
+     * @return bool
+     */
     function add($userdata) {
         if(!$this->writeable) {
             return $this->set_error(_("Addressbook is read-only"));
@@ -294,15 +327,19 @@ class abook_local_file extends addressbook_backend {
 
         /* Test write result */
         if($r === FALSE) {
-        	/* Fail */
-        	$this->set_error(_("Write to addressbook failed"));
-		return FALSE;
-	}
+            /* Fail */
+            $this->set_error(_("Write to addressbook failed"));
+            return FALSE;
+        }
 
         return TRUE;
     }
 
-    /* Delete address */
+    /**
+     * Delete address
+     * @param string $alias alias that has to be deleted
+     * @return bool
+     */
     function remove($alias) {
         if(!$this->writeable) {
             return $this->set_error(_("Addressbook is read-only"));
@@ -334,7 +371,12 @@ class abook_local_file extends addressbook_backend {
         return true;
     }
 
-    /* Modify address */
+    /**
+     * Modify address
+     * @param string $alias modified alias
+     * @param array $userdata new data
+     * @return bool true, if operation successful
+     */
     function modify($alias, $userdata) {
         if(!$this->writeable) {
             return $this->set_error(_("Addressbook is read-only"));
@@ -381,7 +423,11 @@ class abook_local_file extends addressbook_backend {
         return true;
     }
 
-    /* Function for quoting values before saving */
+    /**
+     * Function for quoting values before saving
+     * @param string $value string that has to be quoted
+     * @param string quoted string
+     */
     function quotevalue($value) {
         /* Quote the field if it contains | or ". Double quotes need to
          * be replaced with "" */