Proper phpdoc for Horde_Autoloader

Cleanup some code to Horde coding standards

framework/Autoloader/doc/Horde/Autoloader/examples/most_basic.php

@@ -1,11 +1,12 @@
 <?php
-/** 
+/**
  * Most basic usage example for Horde_Autoloader
  * Load the default Horde Autoloader without any additional parameters
- * In default configuration, the Autoloader tries to load 
+ * In default configuration, the Autoloader tries to load
  * My/Class/Name.php when My_Class_Name is first accessed
  * No require_once statement is needed.
- * */
+ */
+
 require_once 'Horde/Autoloader/Default.php';
 
 /**

framework/Autoloader/lib/Horde/Autoloader.php

@@ -1,35 +1,85 @@
 <?php
 /**
- * Horde_Autoloader
+ * Copyright 2008-2014 Horde LLC (http://www.horde.org/)
+ *
+ * See the enclosed file COPYING for license information (LGPL). If you
+ * did not receive this file, see http://www.horde.org/licenses/lgpl21.
+ *
+ * @category  Horde
+ * @copyright 2008-2014 Horde LLC
+ * @license   http://www.horde.org/licenses/lgpl21 LGPL 2.1
+ * @package   Autoloader
+ */
+
+/**
+ * Horde autoloader implementation.
  *
  * Manages an application's class name to file name mapping conventions. One or
  * more class-to-filename mappers are defined, and are searched in LIFO order.
  *
- * @author   Bob Mckee <bmckee@bywires.com>
- * @author   Chuck Hagenbuch <chuck@horde.org>
- * @category Horde
- * @package  Autoloader
+ * @author    Bob Mckee <bmckee@bywires.com>
+ * @author    Chuck Hagenbuch <chuck@horde.org>
+ * @category  Horde
+ * @copyright 2008-2014 Horde LLC
+ * @license   http://www.horde.org/licenses/lgpl21 LGPL 2.1
+ * @package   Autoloader
  */
 class Horde_Autoloader
 {
-    private $_mappers = array();
+    /**
+     * List of callback methods.
+     *
+     * @var array
+     */
     private $_callbacks = array();
 
+    /**
+     * List of classpath mappers.
+     *
+     * @var array
+     */
+    private $_mappers = array();
+
+    /**
+     * Register the autoloader with PHP (in a way to play well with as many
+     * configurations as possible).
+     */
+    public function registerAutoloader()
+    {
+        spl_autoload_register(array($this, 'loadClass'));
+        if (function_exists('__autoload')) {
+            spl_autoload_register('__autoload');
+        }
+    }
+
+    /**
+     * Loads a class into the current environment by classname.
+     *
+     * @param string $className  Classname to load.
+     *
+     * @return boolean  True if the class was successfully loaded.
+     */
     public function loadClass($className)
     {
-        if ($path = $this->mapToPath($className)) {
-            if ($this->_include($path)) {
-                $className = strtolower($className);
-                if (isset($this->_callbacks[$className])) {
-                    call_user_func($this->_callbacks[$className]);
-                }
-                return true;
+        if (($path = $this->mapToPath($className)) &&
+            $this->_include($path)) {
+            $className = strtolower($className);
+            if (isset($this->_callbacks[$className])) {
+                call_user_func($this->_callbacks[$className]);
             }
+            return true;
         }
 
         return false;
     }
 
+    /**
+     * Adds a class path mapper to the beginning of the queue.
+     *
+     * @param Horde_Autoloader_ClassPathMapper $mapper  A mapper object.
+     *
+     * @return Horde_Autoloader  This instance.
+     */
     public function addClassPathMapper(Horde_Autoloader_ClassPathMapper $mapper)
     {
         array_unshift($this->_mappers, $mapper);
@@ -47,37 +97,47 @@ public function addCallback($class, $callback)
         $this->_callbacks[strtolower($class)] = $callback;
     }
 
-    public function registerAutoloader()
-    {
-        // Register the autoloader in a way to play well with as many
-        // configurations as possible.
-        spl_autoload_register(array($this, 'loadClass'));
-        if (function_exists('__autoload')) {
-            spl_autoload_register('__autoload');
-        }
-    }
-
     /**
      * Search registered mappers in LIFO order.
+     *
+     * @param string $className  Classname to load.
+     *
+     * @return mixed  Pathname to class, or null if not found.
      */
     public function mapToPath($className)
     {
         foreach ($this->_mappers as $mapper) {
-            if ($path = $mapper->mapToPath($className)) {
-                if ($this->_fileExists($path)) {
-                    return $path;
-                }
+            if (($path = $mapper->mapToPath($className)) &&
+                $this->_fileExists($path)) {
+                return $path;
             }
         }
+
+        return null;
     }
 
+    /**
+     * Include a file.
+     *
+     * @param string $path  Pathname of file to include.
+     *
+     * @return boolean  Success.
+     */
     protected function _include($path)
     {
         return (bool)include $path;
     }
 
+    /**
+     * Does a file exist?
+     *
+     * @param string $path  Pathname of file to check.
+     *
+     * @return boolean  Does file exist?
+     */
     protected function _fileExists($path)
     {
         return file_exists($path);
     }
+
 }

framework/Autoloader/lib/Horde/Autoloader/ClassPathMapper.php

@@ -1,14 +1,34 @@
 <?php
 /**
- * Horde_Autoloader_ClassPathMapper
+ * Copyright 2008-2014 Horde LLC (http://www.horde.org/)
  *
- * Interface for class loaders
+ * See the enclosed file COPYING for license information (LGPL). If you
+ * did not receive this file, see http://www.horde.org/licenses/lgpl21.
  *
- * @author   Bob Mckee <bmckee@bywires.com>
- * @category Horde
- * @package  Autoloader
+ * @category  Horde
+ * @copyright 2008-2014 Horde LLC
+ * @license   http://www.horde.org/licenses/lgpl21 LGPL 2.1
+ * @package   Autoloader
+ */
+
+/**
+ * Interface for autoloader class path mappers.
+ *
+ * @author    Bob Mckee <bmckee@bywires.com>
+ * @category  Horde
+ * @copyright 2008-2014 Horde LLC
+ * @license   http://www.horde.org/licenses/lgpl21 LGPL 2.1
+ * @package   Autoloader
  */
 interface Horde_Autoloader_ClassPathMapper
 {
+    /**
+     * Search for a mapping from class to file path.
+     *
+     * @param string $className  Classname to load.
+     *
+     * @return mixed  Pathname to class, or false if not found.
+     */
     public function mapToPath($className);
+
 }

framework/Autoloader/lib/Horde/Autoloader/ClassPathMapper/Application.php

@@ -1,18 +1,30 @@
 <?php
 /**
- * Provides a generic pattern for different mapping types within the application
- * directory.
+ * Copyright 2008-2014 Horde LLC (http://www.horde.org/)
  *
- * @author   Bob Mckee <bmckee@bywires.com>
- * @author   Chuck Hagenbuch <chuck@horde.org>
- * @category Horde
- * @package  Autoloader
+ * See the enclosed file COPYING for license information (LGPL). If you
+ * did not receive this file, see http://www.horde.org/licenses/lgpl21.
+ *
+ * @category  Horde
+ * @copyright 2008-2014 Horde LLC
+ * @license   http://www.horde.org/licenses/lgpl21 LGPL 2.1
+ * @package   Autoloader
  */
-class Horde_Autoloader_ClassPathMapper_Application implements Horde_Autoloader_ClassPathMapper
-{
-    protected $_appDir;
-    protected $_mappings = array();
 
+/**
+ * Provides a classmapper that implements generic pattern for different
+ * mapping types within the application directory.
+ *
+ * @author    Bob Mckee <bmckee@bywires.com>
+ * @author    Chuck Hagenbuch <chuck@horde.org>
+ * @category  Horde
+ * @copyright 2008-2014 Horde LLC
+ * @license   http://www.horde.org/licenses/lgpl21 LGPL 2.1
+ * @package   Autoloader
+ */
+class Horde_Autoloader_ClassPathMapper_Application
+implements Horde_Autoloader_ClassPathMapper
+{
     /**
      * The following constants are for naming the positions in the regex for
      * easy readability later.
@@ -23,27 +35,55 @@ class Horde_Autoloader_ClassPathMapper_Application implements Horde_Autoloader_C
 
     const NAME_SEGMENT = '([0-9A-Z][0-9A-Za-z]+)+';
 
+    /**
+     * @var string
+     */
+    protected $_appDir;
+
+    /**
+     * @var array
+     */
+    protected $_mappings = array();
+
+    /**
+     * Constructor.
+     *
+     * @param string $appDir
+     */
     public function __construct($appDir)
     {
         $this->_appDir = rtrim($appDir, '/') . '/';
     }
 
+    /**
+     * @param string $classSuffix
+     * @param string $subDir
+     */
     public function addMapping($classSuffix, $subDir)
     {
         $this->_mappings[$classSuffix] = $subDir;
-        $this->_classMatchRegex = '/^' . self::NAME_SEGMENT . '_' . self::NAME_SEGMENT . '_' .
+        $this->_classMatchRegex = '/^' . self::NAME_SEGMENT . '_' .
+            self::NAME_SEGMENT . '_' .
             '(' . implode('|', array_keys($this->_mappings)) . ')$/';
     }
 
+    /**
+     */
     public function mapToPath($className)
     {
         if (preg_match($this->_classMatchRegex, $className, $matches)) {
             return $this->_appDir . $this->_mappings[$matches[self::SUFFIX_POS]] . '/' . $matches[self::ACTION_POS] . '.php';
         }
     }
 
+    /**
+     * String representation of class.
+     *
+     * @return string
+     */
     public function __toString()
     {
         return get_class($this) . ' ' . $this->_classMatchRegex . ' [' . $this->_appDir . ']';
     }
+
 }