These suggestions look good to me, and seem to summarize standards used
by the better commented classes already in the framework.
Regarding method comments, I like Thomas' approach using the word
OPTIONAL for optional parameters, and then adding the default value thusly:
* @param bool $param2 - OPTIONAL Description goes here (default:
false)
* @param string|array $flags - A flag or array of flags.
I also like Thomas' style of lining things up under a hyphen, making a clear
visual distinction between the names of the parameters and their descriptions.
If we agree to this convention, then someone can easily implement a tool to
check for which files fail to follow the convention.
Cheers,
Gavin
Ralph Schindler wrote:
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;
}
----|---------------------------------------------------------------------------
