he" 来指代那个对象或者是变量
避免空话，废话，对于你所要给出的api，在你的api后面要有它的功能描述，是其能够"自成文档"。所谓的空话，废话是指，你的描述不是功能描述，而只是api名称的简单重复和罗列，或者是用另一个api来解释这个api，到头来，你的读者也不知道你所要表达的内容实质。你的描述，应该是那些从你的类名，方法名，或者是函数名看不到的补充的信息，而不是把你的api名称再重复一遍。很多人可能很多人（包括我）不知不觉中就犯了这个错误，下面是一个例子：
/**
* 设置用户记录集
*
* @param text 给定的表名
*/
function set_user_record($table) {
你从上面这段注释中能够知道什么？因此，这段注释实际上是废话，因为你从函数名称上是可以看出的，下面是改进后的：
/**
* 打开系统用户表并设置为当前用户记录集，此记录集将用于随后相关用户数据更新操作的缺省记录集。如果失败则抛出一个数据库错误。
*
* @param text 要打开的系统用户表的表名。
*/
function set_user_record($table) {
适当地使用链接。为你文档中引用的api名称（包括你的其他类及方法，php的函数等）添加适当的链接是很受欢迎的：你可以使用@link标记来添加到相关的api的链接，不过，你没有必要为文档中引用的所有的api都添加连接，这样会很不美观，这里有一个简单的标准：如果用户在这个地方看到某个api，确实希望要去点击以便获取更多信息，这样有助于他们去理解你的文档，并且即使添加了链接，只在它第一出现的是时候添加，没有必要重复添加相同的link。
由于phpdoc的功能限制，一个php文件只定义一个类或模块，不要把类和模块的定义放在同一个文件里，否则phpdoc可能无法工作，至少目前版本是这样。如果你的框架使用oop来构建，应避免同时使用模块或模块组；同时应该仔细规划你的应用结构，你的应用框架应该是一个类似树型的结构，顶层的分支不要太多，例如你可以设计2个超类，分别是作为正常应用和错误处理的超类，其余的都从这2个类派生出来。
4. 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等等。虽然这些特性没有从语言级别得到支持，不过从使用者角度来遵循这些特性，仍是值得推荐的。
举例：
/**
* 这是一个绘五星图案的抽象类.
* @abstract
避免空话，废话，对于你所要给出的api，在你的api后面要有它的功能描述，是其能够"自成文档"。所谓的空话，废话是指，你的描述不是功能描述，而只是api名称的简单重复和罗列，或者是用另一个api来解释这个api，到头来，你的读者也不知道你所要表达的内容实质。你的描述，应该是那些从你的类名，方法名，或者是函数名看不到的补充的信息，而不是把你的api名称再重复一遍。很多人可能很多人（包括我）不知不觉中就犯了这个错误，下面是一个例子：
/**
* 设置用户记录集
*
* @param text 给定的表名
*/
function set_user_record($table) {
你从上面这段注释中能够知道什么？因此，这段注释实际上是废话，因为你从函数名称上是可以看出的，下面是改进后的：
/**
* 打开系统用户表并设置为当前用户记录集，此记录集将用于随后相关用户数据更新操作的缺省记录集。如果失败则抛出一个数据库错误。
*
* @param text 要打开的系统用户表的表名。
*/
function set_user_record($table) {
适当地使用链接。为你文档中引用的api名称（包括你的其他类及方法，php的函数等）添加适当的链接是很受欢迎的：你可以使用@link标记来添加到相关的api的链接，不过，你没有必要为文档中引用的所有的api都添加连接，这样会很不美观，这里有一个简单的标准：如果用户在这个地方看到某个api，确实希望要去点击以便获取更多信息，这样有助于他们去理解你的文档，并且即使添加了链接，只在它第一出现的是时候添加，没有必要重复添加相同的link。
由于phpdoc的功能限制，一个php文件只定义一个类或模块，不要把类和模块的定义放在同一个文件里，否则phpdoc可能无法工作，至少目前版本是这样。如果你的框架使用oop来构建，应避免同时使用模块或模块组；同时应该仔细规划你的应用结构，你的应用框架应该是一个类似树型的结构，顶层的分支不要太多，例如你可以设计2个超类，分别是作为正常应用和错误处理的超类，其余的都从这2个类派生出来。
4. 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等等。虽然这些特性没有从语言级别得到支持，不过从使用者角度来遵循这些特性，仍是值得推荐的。
举例：
/**
* 这是一个绘五星图案的抽象类.
* @abstract
相关文章
 我来说两句 |
对此文章发表了评论 |
评论列表 （最新 评论仅限网友观点！）
推荐文章
热门文章
