Documentation Blocks

All source code files should contain a "file-level" docblock at the top of each file and a "class-level" docblock immediately above each class. The only exception to this rule is where a file contains a single class. In this case only the class docblock is required. Included is a brief example of such docblocks, see the index below for more in-depth examples.

/**
 * @file
 *
 * Short description for file.
 *
 * Long description for file (if any)...
 *
 * @ingroup    GroupName
 * @author     Original Author <author@example.com>
 * @author     Another Author {@link http://example.com}
 * @copyright  1997-2005 Supernerd, LLC and Contributors
 * @license    http://www.gnu.org/copyleft/gpl.html  GPL License 2 or later
 * @version    CVS: $Id:$
 * @link       http://www.zoopframework.com/
 * @see        Zoop::zoop
 * @since      File available since Release 1.2.0
 * @deprecated File deprecated in Release 2.0.0
 */
 
/*
 * Place includes, constant defines and $_GLOBAL settings here.
 * Make sure they have appropriate docblocks to avoid phpDocumentor
 * construing they are documented by the page-level docblock.
 */
 
/**
 * Short description for class.
 *
 * Long description for class (if any)...
 *
 * @ingroup    GroupName
 * @ingroup    AnotherGroup
 * @author     Original Author <author@example.com>
 * @author     Another Author {@link http://example.com}
 * @copyright  1997-2005 Supernerd, LLC and Contributors
 * @license    http://www.gnu.org/copyleft/gpl.html  GPL License 2 or later
 * @version    CVS: $Id:$
 * @link       http://www.zoopframework.com
 * @see        Zoop, Zoop::zoop()
 * @since      Class available since Release 1.2.0
 * @deprecated Class deprecated in Release 2.0.0
 */
class Foo {
 
    /**
     * Brief method description.
     *
     * Extended description for method (if any)...
     * 
     * @code
     *   //code examples can be added with @ code blocks
     *   $var = fooFunction($arg);
     * @endcode
     *
     * @param mixed $arg1 Argument 1 description.
     * @param mixed $arg3 Argument 2 short description.
     *   Extended description for Argument 2. Perhaps talk about the default value?
     * @access public
     * @return mixed Return value description.
     *   Can also have an extended definition.
     */
    function fooFunction($arg1, $arg2 = 'default') {
        if (condition) {
            statement;
        }
        return $val;
    }
}

@mainpage

Every branch of Zoop should contain one @mainpage docblock. This docblock is currently found in zoop.php, and looks something like this:

/**
 * @mainpage Welcome to the Zoop Framework
 * 
 * Welcome to the Zoop Framework. Newcomers to Zoop should check out
 * {@link http://zoopframework.com/docs/from-a-to-zoop From A to Zoop},
 * a beginner's guide to Zoop.
 *
 * - {@link http://zoopframework.com/docs Zoop Documentation}
 *   - {@link http://zoopframework.com/docs/from-a-to-zoop From A to Zoop}
 *   - {@link http://zoopframework.com/docs/user-manual The Zoop Users Manual}
 *   - {@link http://zoopframework.com/docs/cookbook The Zoop Cookbook}
 * - {@link http://zoopframework.com/docs/user-manual/components Zoop Components}
 *   - App
 *   - Auth
 *   - Cache
 *   - Chart
 *
 * ...
 */

The @mainpage docblock is used as the landing page for the branch at api.zoopframework.com. You may also define sections, subsections and subsubsections to break up more complex documentation pages:

/**
 * @section sectionName Section Title
 * ...
 *
 * @subsection subSectionName Subsection Title
 * ...
 *
 * @subsubsection subSubSectionName Subsection Title
 * ...
 *
 */