PEAR：使用PHPDoc轻松建立你的PEAR文档（2）基本指南
|
- UID
- 1066743
|
PEAR：使用PHPDoc轻松建立你的PEAR文档（2）基本指南
3.4 文档书写指南在你描述你的代码的用途或者是功能的时候，最好能够遵循大多数人的习惯，通俗地讲就是"你告诉我的信息正是我想要知道的"。为此，这里将介绍一些书写文档注释的技巧和规范，希望能够对你有所帮助：
- 使用 <code> 来标志关键字和命名及相关的代码。如果在文档中需要引用一些关键字，变量名，或者是你要给出一些代码的例子，那么你最好使用<code></code>来将这些关键字，变量名，代码片段和你的文档分隔开，这样，读者阅读的时候，将会知道，这些将是运行的代码，关键字而不是你的描述性的语言。
- 使用简单，明确的语言，避免冗长，复杂，晦涩的长句来描述。尤其是在功能简述，参数说明等索引部分中，尽量使用简单明白的语言揭示主要的信息，把其他的细节放在详细说明部分去阐述。如果你使用英语，建议使用短语而不一定是句子。
- 如果使用英语，建议使用第3人称单数的形式来说明
- 在给方法，函数说明的时候，你需要说明的是这个方法"作了什么"，而不是"怎么做"。因此，建议你的说明是以动词开始，比如"返回记录数"，"删除给定的记录"等等。
- 当你引用的某个对象或者变量是从当前的类中建立的，那么使用 "this" 代替 "the" 来指代那个对象或者是变量
- 避免空话，废话，对于你所要给出的API，在你的API后面要有它的功能描述，是其能够"自成文档"。所谓的空话，废话是指，你的描述不是功能描述，而只是API名称的简单重复和罗列，或者是用另一个API来解释这个API，到头来，你的读者也不知道你所要表达的内容实质。你的描述，应该是那些从你的类名，方法名，或者是函数名看不到的补充的信息，而不是把你的API名称再重复一遍。很多人可能很多人（包括我）不知不觉中就犯了这个错误，下面是一个例子：
1
2
3
4
5
6
| /**
* 设置用户记录集
*
* @param text 给定的表名
*/
function set_user_record($table) {
|
你从上面这段注释中能够知道什么？因此，这段注释实际上是废话，因为你从函数名称上是可以看出的，下面是改进后的：
1
2
3
4
5
6
7
| /**
* 打开系统用户表并设置为当前用户记录集，此记录集将用于随后相关用户数据更新操作的缺省记录集。
如果失败则抛出一个数据库错误。
*
* @param text 要打开的系统用户表的表名。
*/
function set_user_record($table) {
|
- 适当地使用链接。为你文档中引用的API名称（包括你的其他类及方法，PHP的函数等）添加适当的链接是很受欢迎的：你可以使用@link标记来添加到相关的API的链接，不过，你没有必要为文档中引用的所有的API都添加连接，这样会很不美观，这里有一个简单的标准：如果用户在这个地方看到某个API，确实希望要去点击以便获取更多信息，这样有助于他们去理解你的文档，并且即使添加了链接，只在它第一出现的是时候添加，没有必要重复添加相同的LINK。
- 由于PHPDOC的功能限制，一个PHP文件只定义一个类或模块，不要把类和模块的定义放在同一个文件里，否则PHPDOC可能无法工作，至少目前版本是这样。如果你的框架使用OOP来构建，应避免同时使用模块或模块组；同时应该仔细规划你的应用结构，你的应用框架应该是一个类似树型的结构，顶层的分支不要太多，例如你可以设计2个超类，分别是作为正常应用和错误处理的超类，其余的都从这2个类派生出来。
PHPDoc关键字及文档标志4.1 关键字class 、function 、var 、include (include_once, require, require_once) 、define
在以上这些关键字前面所做的注释，都被认为是文档性注释。
4.2 文档标记说明：使用范围是指该标记可以用来修饰的关键字，或其他文档标记
@abstract 使用范围：class, function, var
说明当前类是一个抽象类。
注释：从PHP语言角度来说，它并不象JAVA，C++那样，支持抽象类这个概念。也没有相应的关键字来修饰某个类是抽象类。由于PHPDOC实际上大部分是借鉴了JAVADOC的做法，因此很多文档标记也是直接从JAVADOC中沿袭过来，如abstract,access,final等等。虽然这些特性没有从语言级别得到支持，不过从使用者角度来遵循这些特性，仍是值得推荐的。
举例：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
| /**
* 这是一个绘五星图案的抽象类.
* @abstract
*/
class paint_start {
/**
* 绘制数量
* @abstract
*/
var $number;
/**
* 绘制五星图案
* @abstract
*/
function paint() {
;
}
}
|
@access (public|private) 使用范围：class, function, var, define, module
指明这个变量、类、函数/方法的存取权限。如果你的函数是内部使用，你应该指明它为private,这样的好处是，即使PHP不能阻止其他的人使用你的私有数据，但是至少你向你的用户传达这样的信息，这是一个私有的函数，因此不保证在将来的版本中仍存在；对于使用者而言，表示为@private的数据和方法，你不应该直接使用，即使你可以这样做。
举例：
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
| /**
* 这是一个绘五星图案的抽象类.
* @abstract
* @access public
*/
class paint_start {
/**
* 绘制数量
* @abstract
* @access private
*/
var $number;
/**
* 绘制五星图案
* @abstract
* @access public
*/
function paint() {
;
}
}
|
@author Name [<email>] [, ...] 使用范围：class, function, var, define, module, use
指明作者信息,依次是作者姓名，email地址，其他的通讯信息。如果有多个作者，按照其先后次序，使用多个@author依次列出：
@brother (function()|$variable) 使用范围：class, function, var, define, module, use
@sister (function()|$variable) 使用范围：class, function, var, define, module, use |
|
|
|
|
|
