I have attached a document that has examples, that can be used as cut
and paste, or templates in Zend Studio for the purposes of standardizing
docblocks. This document is attached due to the line restrictions in
email. Coding standards have an 80 character limit, whereas email might
truncate some lines that push limits.
Darby has posted an issue related to this in Jira as ZF-559. I propose
this document as the first step in cleanup is deciding on these standards.
Bill has suggested in issue ZF-507 that inconsistent copyright and
license info is used. This doc also aims to be the first step in that
cleanup as well. Bill, please comment on this as per zend's official
legalese stuff.
Things to note:
* I have removed copyright and license from class doc block since these
elements pertain more to files than they do to classes.
* I have made the year in copyright year 2007, soon to be an issue in
old files ;)
* Use of subpackage when appropriate, for apidoc purposes.
* Standard require_once docblocks
-Ralph
References:
http://framework.zend.com/issues/browse/ZF-507
http://framework.zend.com/issues/browse/ZF-559
I. Standard DocBlocks v 1.0
1. File Header
a. The optional @subpackage should be considered when appropriate.
see 2.a
b. The optional @since tag should also be considered when appropriate.
----------------|---------------------------------------------------------------
<?php
/**
* Zend Framework
*
* LICENSE
*
* This source file is subject to the new BSD license that is bundled
* with this package in the file LICENSE.txt.
* It is also available through the world-wide-web at this URL:
* http://framework.zend.com/license/new-bsd
* If you did not receive a copy of the license and are unable to
* obtain it through the world-wide-web, please send an email
* to [EMAIL PROTECTED] so we can send you a copy immediately.
*
* @category Zend
* @package Zend_<<package>>
* @copyright Copyright (c) 2007 Zend Technologies USA Inc. (www.zend.com)
* @link http://framework.zend.com
* @license http://framework.zend.com/license/new-bsd New BSD License
* @version $Id$
*/
----------------|---------------------------------------------------------------
2. Class Header
a. @subpackage - This should be used when you have a logical subpackage
within your components class. An example of this would a component that
utilizes an adapter approach, or implements an interface. It follows
the same format as @package
----------------|---------------------------------------------------------------
/**
* Zend_<<class>> - short description...
*
* @category Zend
* @package Zend_<<package>>
*/
class Zend_<<class>>
----------------|---------------------------------------------------------------
3. Class Requirements (require_once)
----------------|---------------------------------------------------------------
/**
* @uses Zend_Some_Other_Class
*/
require_once 'Zend/Some/Other/Class.php';
----------------|---------------------------------------------------------------
4. Properties
a. property_name - short description
b. @var and variable type (optional notes)
----|---------------------------------------------------------------------------
/**
* _instance - Singleton instance
*
* @var Zend_Component This property set by the getInstance method
*/
static protected $_instance = null;
----|---------------------------------------------------------------------------
5. Methods
----|---------------------------------------------------------------------------
/**
* methodName() - short description..
*
* Long Description. Perhaps some code examples if necessary.
*
* @param Component_Object $param1
* @param bool $param2 Default is false
* @throws Some_Exception Does this when something goes wrong.
* @return void
*/
public function methodName(Component_Object $param1, $param2 = false)
{
/**
* ... code ...
*/
if (!is_bool($param2)) {
throw new Some_Exception('Not bool');
}
return;
}
----|---------------------------------------------------------------------------
