第3章 注释规则
3.1 一般规则
不写不必要的注释；只有当代码不能很好地说明逻辑时，才用注释补充；
把注释看成程序的一部分，在编写/维护代码时同时编写/维护注释；
注释完全采用PHPDocumentor的规范，以方便用其生成API级文档。
3.2 详细规则
请参见PHPDocumentor手册。下边给出各个部分的注释示范。
3.2.1 版权信息
注释名称 版权信息
注释示范：
复制代码 代码如下:
//
// +----------------------------------------------------+
// | phpDocumentor |
// +----------------------------------------------------+
// | Copyright (c) 2000-2003 Joshua Eichorn |
// | Email jeichorn@phpdoc.org |
// | Web |
// +----------------------------------------------------+
// | This source file is subject to PHP License |
// +----------------------------------------------------+
//
备注 使用//来标示版权信息，以免和PHPDocumentor的page-level DocBlock发生冲突
3.2.2文件头注释示例
注释名称 文件头注释
注释示范：
PHP 代码：
复制代码 代码如下:
/**
* All abstract representations of inline tags are in this file
* @package phpDocumentor
* @subpackage InlineTags
* @since separate file since version 1.2
* @version $Id $
*/
备注
1）文件头注释需要指明所属的包和子包；
2）在@version中加上$ID，以方便使用CVS管理文件。
3.2.3 类注释示例
注释名称 类注释
注释示范：
PHP 代码:
复制代码 代码如下:
/**
* Use this element to represent an {@}inline tag} like {@}link}
* @see parserStringWithInlineTags
* @package phpDocumentor
* @subpackage InlineTags
* @author Greg Beaver <cellog@users.sourceforge.net>
* @since 1.0rc1
* @version $Revision: 1.21.2.6 $
* @tutorial inlinetags.pkg
*/
3.2.4 类属性注释示例
注释名称 类属性注释
注释示范：
PHP 代码:
复制代码 代码如下:
/**
* Element type
*
* Type is used by many functions to skip the hassle of
*
* <code>
* if get_class($blah) == 'parserBlah'
* </code>
* always "inlinetag"
* @var string
*/
var $type = 'inlinetag';
3.2.5 函数/类方法注释示例
注释名称 函数/类方法注释
注释示范：
PHP 代码:
复制代码 代码如下:
/**
* @return string always ''
* calculate the short description of a DocBlock
* @see parserStringWithInlineTags::getString()
* @see parserStringWithInlineTags::trimmedStrlen()
*/
function getString()
{
return '';
}
您可能感兴趣的文章: