我们开发所有类都会使用PHPDoc风格注释这样就能很容易地为所有类构建API文档PHPDoc建立在Sun公司Javadoc系统基础的上这是种为所有、参数、变量和包加注释简单思路方法以便于开发人员轻松地重用这些、参数、变量和包

　　尽管这点对于这个Web应用开发并不太重要但开发过程中使用这种风格注释是个好习惯另外查看本书中代码举例时你会发现每个前面有个PHPDoc注释块确实很有用

　　注解

　　本书中列出代码通常不包含PHPDoc注释在正文中会对这些代码做详细解释和介绍说明不过这个Web应用下载代码中会尽可能包含PHPDoc注释

　　PHPDoc做法是在每个、类或变量定义前放置个注释块并不是所有情况下都要求如此只是在必要情况下才这么做

　　每个注释块最前面是个描述然后是个或多个可选参数例如向个增加PHPDoc注释时可以指定输入参数和返回值数据显然为变量定义所编写PHPDoc注释则包含区别信息

　　以下代码显示了为个简单用户自定义编写PHPDoc注释例子:



　　首先要注意注释块如何开始/**指示PHPDoc解析器个PHPDoc注释已经开始

　　注释块第行是个简短描述我个人喜好是在此只写、类或变量名

　　注释块中下部分是个比较长描述在这里我会尽力以种黑盒观点描述、类或变量作用也就是说它会做什么而不是它怎样做所有具体功能或繁杂逻辑都由代码中标准注释来解释

　　注解

　　尽管不是必需不过通常约定是在/** … */块每行起始处包含个星号这主要是为了提高可读性还能容易地发现整个PHPDoc块

　　注释块中最后部分包含各个PHPDoc参数解析器用这些参数来更好地链接API文档从而为你提供实用文档每个参数最前面是个@后面紧跟着参数名然后是该参数所需信息

　　这个例子中可以看到@param和@参数@param用于指定参数各个方面:首先是参数类型(在这里第个参数是个串)；接下来是参数名(这里是$name)；最后是个简短描述介绍说明输入数据应当包含哪些内容@参数用于提供所返回数据有关信息:先指定数据类型然后是返回数据所包含内容个简短描述