-- Gavin Vess <[EMAIL PROTECTED]> wrote (on Tuesday, 02 January 2007, 02:18 PM -0800): > 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.
I like the 'OPTIONAL' tagging -- I do the same in my code (but not usu. all caps). I do *not* like the hyphen. It's redundant to how phpdoc processes the documentation. > 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; > > } > > > >----|--------------------------------------------------------------------------- > -- Matthew Weier O'Phinney PHP Developer | [EMAIL PROTECTED] Zend - The PHP Company | http://www.zend.com/
