Happy 2014

[squirrelmail.git] / class / mime / Rfc822Header.class.php

diff --git a/class/mime/Rfc822Header.class.php b/class/mime/Rfc822Header.class.php
index 57a44d6eb4b657ddaacc8b10e31cbf35d480023a..717b09de45c364c9cb6a07b5443e0b9cc512e15c 100644 (file)
--- a/class/mime/Rfc822Header.class.php
+++ b/class/mime/Rfc822Header.class.php
@@ -5,7 +5,7 @@
  *
  * This file contains functions needed to handle headers in mime messages.
  *
- * @copyright 2003-2012 The SquirrelMail Project Team
+ * @copyright 2003-2014 The SquirrelMail Project Team
  * @license http://opensource.org/licenses/gpl-license.php GNU Public License
  * @version $Id$
  * @package squirrelmail
@@ -736,7 +736,7 @@ class Rfc822Header {
             $value = substr($value,strlen($charset)+1);
             /* FIXME: What's the status of charset decode with language information ????
              * Maybe language information contains only ascii text and charset_decode() 
-             * only runs htmlspecialchars() on it. If it contains 8bit information, you 
+             * only runs sm_encode_html_special_chars() on it. If it contains 8bit information, you 
              * get html encoded text in charset used by selected translation.
              */
             $value = charset_decode($charset,$value);
@@ -950,9 +950,50 @@ class Rfc822Header {
 
     /**
 //FIXME: This needs some documentation (inside the function too)!  Don't code w/out comments!
-     * @param mixed $address array or string
-     * @param boolean $recurs
-     * @return mixed array, boolean
+     * Looking at the code years after it was written,
+     * this is my (Paul) best guess as to what this
+     * function does (note that docs previously claimed
+     * that this function returns boolean or an array,
+     * but it no longer appears to return an array - an
+     * integer instead):
+     *
+     * Inspects the TO and CC headers of the message
+     * represented by this object, looking for the
+     * address(es) given by $address
+     *
+     * If $address is a string:
+     *    Serves as a test (returns boolean) as to
+     *    whether or not the given address is found
+     *    anywhere in the TO or CC headers
+     *
+     * If $address is an array:
+     *    Looks through this list of addresses and
+     *    returns the array index (an integer even
+     *    if the array is given with keys of a
+     *    different type) of the *last* matching
+     *    $address found in this message's
+     *    TO or CC headers, unless there is an exact
+     *    match (meaning that the "personal
+     *    information" in addition to the email
+     *    address also matches), in which case that
+     *    index (the first one found) is returned
+     *
+     * @param mixed $address Address(es) to search for in this
+     *                       message's TO and CC headers - please
+     *                       see above how the format of this
+     *                       argument affects the return value
+     *                       of this function
+     * @param boolean $recurs FOR INTERNAL USE ONLY
+     *
+     * @return mixed Boolean when $address is a scalar,
+     *               indicating whether or not the address
+     *               was found in the TO or CC headers.
+     *               An integer when $address is an array,
+     *               containing the index of the value in
+     *               that array that was found in the TO
+     *               or CC headers, or boolean FALSE if
+     *               there were no matches at all
+     *
      * @since 1.3.2
      */
     function findAddress($address, $recurs = false) {
@@ -1005,7 +1046,7 @@ class Rfc822Header {
             }
             if ($recurs) {
                 return array($results, false);
-            } elseif (count($result)) {
+            } elseif (count($results)) {
                 return true;
             } else {
                 return false;