给php代码添加规范的注释phpDocumentor

时间:2024-03-24 20:34:08

给php代码添加规范的注释
更多参考 http://phpdoc.org/docs/latest/index.html
在phpdocumentor中,注释分为文档性注释和非文档性注释。
所谓文档性注释,是那些放在特定关键字前面的多行注释,特定关键字是指能够被phpdoc分析的关键字,例如class,var等,具体的可参加附录1.
那些没有在关键字前面或者不规范的注释就称作非文档性注释,这些注释将不会被phpdoc所分析,也不会出现在你产生的api文当中。
3.2如何书写文档性注释:
所 有的文档性注释都是由/**开始的一个多行注释,在phpDocumentor里称为DocBlock, DocBlock是指软件开发人员编写的关于某个关键字的帮助信息,使得其他人能够通过它知道这个关键字的具体用途,如何使用。 PhpDocumentor规定一个DocBlock包含如下信息:
1. 功能简述区
2. 详细说明区
3. 标记tag
文档性注释的第一行是功能描述区,正文一般是简明扼要地说明这个类,方法或者函数的功能,功能简述的正文在生成的文档中将显示在索引区。功能描述区的内容可以通过一个空行或者 . 来结束
在 功能描述区后是一个空行,接着是详细说明区,. 这部分主要是详细说明你的API的功能,用途,如果可能,也可以有用法举例等等。在这部分,你应该着重阐明你的API函数或者方法的通常的用途,用法,并 且指明是否是跨平台的(如果涉及到),对于和平台相关的信息,你要和那些通用的信息区别对待,通常的做法是另起一行,然后写出在某个特定平台上的注意事项 或者是特别的信息,这些信息应该足够,以便你的读者能够编写相应的测试信息,比如边界条件,参数范围,断点等等。
之后同样是一个空白行,然后是文档的标记tag,指明一些技术上的信息,主要是最主要的是调用参数类型,返回值极其类型,继承关系,相关方法/函数等等。

文档注释中还可以使用例如<b> <code>这样的标签

5.文档标记:
文档标记的使用范围是指该标记可以用来修饰的关键字,或其他文档标记。
所有的文档标记都是在每一行的 * 后面以@开头。如果在一段话的中间出来@的标记,这个标记将会被当做普通内容而被忽略掉。
6.一些注释规范
a.注释必须是
/**
* XXXXXXX
*/
的形式
b.对于引用了全局变量的函数,必须使用glboal标记。
c.对于变量,必须用var标记其类型(int,string,bool...)
d.函数必须通过param和return标记指明其参数和返回值
e.对于出现两次或两次以上的关键字,要通过ingore忽略掉多余的,只保留一个即可
f.调用了其他函数或类的地方,要使用link或其他标记链接到相应的部分,便于文档的阅读。
g.必要的地方使用非文档性注释,提高代码易读性。
h.描述性内容尽量简明扼要,尽可能使用短语而非句子。
i.全局变量,静态变量和常量必须用相应标记说明
<?php
/**
* @name 名字
* @abstract 申明变量/类/方法
* @access 指明这个变量、类、函数/方法的存取权限
* @author 函数作者的名字和邮箱地址
* @category 组织packages
* @copyright 指明版权信息
* @const 指明常量
* @deprecate 指明不推荐或者是废弃的信息MyEclipse编码设置
* @example 示例
* @exclude 指明当前的注释将不进行分析,不出现在文挡中
* @final 指明这是一个最终的类、方法、属性,禁止派生、修改。
* @global 指明在此函数中引用的全局变量
* @include 指明包含的文件的信息
* @link 定义在线连接
* @module 定义归属的模块信息
* @modulegroup 定义归属的模块组
* @package 定义归属的包的信息
* @param 定义函数或者方法的参数信息
* @return 定义函数或者方法的返回信息
* @see 定义需要参考的函数、变量,并加入相应的超级连接。
* @since 指明该api函数或者方法是从哪个版本开始引入的
* @static 指明变量、类、函数是静态的。
* @throws 指明此函数可能抛出的错误异常,极其发生的情况
* @todo 指明应该改进或没有实现的地方
* @var 定义说明变量/属性。
* @version 定义版本信息
*/
function XXX($a){..}

  

<?php
/**
* Sample File 2, phpDocumentor Quickstart
*
* This file demonstrates the rich information that can be included in
* in-code documentation through DocBlocks and tags.
* @author Greg Beaver <cellog@php.net>
* @version 1.0
* @package sample
*/ //PHP code /**
* A sample function docblock
* @global string document the fact that this function uses $_myvar
* @staticvar integer $staticvar this is actually what is returned
* @param string $param1 name to declare
* @param string $param2 value of the name
* @return integer
*/
function firstFunc($param1, $param2 = 'optional') {
static $staticvar = 7;
global $_myvar;
return $staticvar;
}