php类文件命名规范

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

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

　　注解

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

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

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

所有的文档标记都是在每一行的 * 后面以@开头。如果在一段话的中间出来@的标记，这个标记将会被当做普通内容而被忽略掉。

@access

使用范围：class,function,var,define,module
该标记用于指明关键字的存取权限：private、public或proteced
@author
指明作者
@copyright
使用范围：class，function，var，define，module，use
指明版权信息
@deprecated
使用范围：class，function，var，define，module，constent，global，include
指明不用或者废弃的关键字
@example
该标记用于解析一段文件内容，并将他们高亮显示。Phpdoc会试图从该标记给的文件路径中读取文件内容
@const
使用范围：define
用来指明php中define的常量
@final
使用范围：class,function,var
指明关键字是一个最终的类、方法、属性，禁止派生、修改。
@filesource
和example类似，只不过该标记将直接读取当前解析的php文件的内容并显示。
@global
指明在此函数中引用的全局变量
@ingore
用于在文档中忽略指定的关键字
@license
相当于html标签中的<a>,首先是URL，接着是要显示的内容
例如<a href=” http://www.baidu.com”>百度</a>
可以写作 @license http://www.baidu.com 百度
@link
类似于license
但还可以通过link指到文档中的任何一个关键字
@name
为关键字指定一个别名。
@package
使用范围：页面级别的-> define，function，include
类级别的->class，var，methods
用于逻辑上将一个或几个关键字分到一组。
@abstrcut
说明当前类是一个抽象类
@param
指明一个函数的参数
@return
指明一个方法或函数的返回指
@static
指明关建字是静态的。
@var
指明变量类型
@version
指明版本信息
@todo
指明应该改进或没有实现的地方
@throws
指明此函数可能抛出的错误异常,极其发生的情况
上面提到过，普通的文档标记标记必须在每行的开头以@标记，除此之外，还有一种标记叫做inline tag,用{@}表示，具体包括以下几种：
{@link}
用法同@link
{@source}

显示一段函数或方法的内容

还有其他的一些（可能有重复）

/**
 * @name 名字
 * @abstract 申明变量/类/方法
 * @access 指明这个变量、类、函数/方法的存取权限
 * @author 函数作者的名字和邮箱地址
 * @category 组织packages
 * @copyright 指明版权信息
 * @const 指明常量
 * @deprecate 指明不推荐或者是废弃的信息
 * @example 示例
 * @exclude 指明当前的注释将不进行分析，不出现在文挡中
 * @final 指明这是一个最终的类、方法、属性，禁止派生、修改。
 * @global 指明在此函数中引用的全局变量
 * @include 指明包含的文件的信息
 * @link 定义在线连接
 * @module 定义归属的模块信息
 * @modulegroup 定义归属的模块组
 * @package 定义归属的包的信息
 * @param 定义函数或者方法的参数信息
 * @return 定义函数或者方法的返回信息
 * @see 定义需要参考的函数、变量，并加入相应的超级连接。
 * @since 指明该api函数或者方法是从哪个版本开始引入的
 * @static 指明变量、类、函数是静态的。
 * @throws 指明此函数可能抛出的错误异常,极其发生的情况
 * @todo 指明应该改进或没有实现的地方
 * @var 定义说明变量/属性。
 * @version 定义版本信息
 */

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

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