PHP学习笔记：PHP&Java文档注释

原文地址：http://www.cublog.cn/u/27731/showart.php?id=212274

写文档是一项乏味却不得不做的工作，而编写API级的文档更是意味着大量的重复劳动和难以保持的一致性。
使用文档注释的PHP或JAVA文件经过工具可以产生 列出类、方法、参数、和程序员所需要了解的其他信息，还可以自动处理各个class之间的关系，并据此生成class tree。
该类工具典型的有：phpDocumentor、javadoc。

要点：
1.文档注释必须要加在声明之前才有意义，其他位置的文档注释将会被忽略。
2.文档注释应该加在下秒几种描述的前面：
》类
》接口
》方法
》域
3.文档注释的第一行是方法/类等的简要描述，这是文档注释的一种规则。
4.要解析文档注释，生成文档的工具会查看“/**”之后以及“*/”之间的部分，其中每个“*”都代表了一行的开始。除了第一行，工具会忽略所有加在“*”之前的空格或制表符，其后的部分会生成html文档的一部分。
5.文档注释应该以一个项目的概述作为起始部分。
6.可以在注释中加入HTML标记。应该找出哪些标记在文本注释中可以正常使用。一般说来，改变字体的标记是没有问题的，但改变文本结构的标记则不能在文档注释中使用。
7.所有javadoc/phpdoc标记都是一@作为开始字符，没个标记都必须开始于一个新行。

标记

@author 作者 默认忽略
@version 版本 默认忽略
@param 参数
@return 返回
@see 查看相关 @see 包.类名@see 包.类名#域名@see 包.类名#方法名（参数列表） php为 参考函数
{@link 名称标记} 内联超文本链接 {@link #link to} => to
@since 源自 源自≈php4php5.1 说明当前代码从哪个版本开始可用
@deprecate 反对 用于描述那些只在早期版本中可用的包、类或方法，而目前由于他人还在使用，因此不能删除这些，这些在将来不可用。或 不建议使用的API
@var 类成员变量
@static 静态变量
@global 全局变量
@const 由define定义的常量

@public
@private
@protected

@serial 域描述
@serialField 域名 域类型 域描述
@serialData 数据描述
@abstract to declare a method, class variable, or class that must be re-defined in a child class to be valid.
@access
@copyright
@example
@final
@filesource
@ignore
@license
@name
@internal
@staticvar
@subpackage
@package
@todo
@tutorial
@uses
详情看http://manual.phpdoc.org