PHP注释生成文档

PHP注释

为了让代码更具可读性，需要给出一些关键的提示注释，为了跟好的生成帮助文档，更需要对注释进行规范。这里选用了PhpDocumentor的注释风格，如果需要生成文档，也只要用工具直接生成就行了。

关于PhpDocumentor

项目地址：https://github.com/phpDocumentor/phpDocumentor2
Composer:https://packagist.org/packages/phpdocumentor/phpdocumentor
教程文档：http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html

更多参考:

• https://www.cnblogs.com/chunguang/p/5717629.html

依赖：

• phpDocumentor2,当前支持的PHP版本为5.3或更高、
• ext/iconvPHP5.0开始默认开启
• ext/intl
• The XSL extension可选，只在使用xsl的模板时使用
• Graphviz,可选，用来生成类图

安装：

1. 下载pear

2. 执行php go-pear.phar 输入system，然后全部回车，可安装完成

3. 安装相关依赖 pear install image_graphviz

4. 安装phpDocumentor

    pear channel-discover pear.phpdoc.org
    pear remote-list -c phpdoc
    pear remote-list -c phpdoc
   

   

   7hdXQdy.png

5. 运行phpdoc run -h查看相关帮助

注释详情

文档标记： 文档标记的使用范围是指该标记可以用来修饰的关键字，或其他文档标记。
所有的文档标记都是在每一行的 * 后面以@开头。如果在一段话的中间出来@的标记，这个标记将会被当做普通内容而被忽略掉。

@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标签中的,首先是URL，接着是要显示的内容
　　例如百度
　　可以写作 @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}

docblock的描述标记

 -- 强调/黑体
 -- 用于围绕php代码，可以显示语法高亮

 -- 换行标识，但有可能被一些文档转换器忽略
 -- 斜体，用于表示重要的内容
 -- 代表键盘输入/屏幕显示
 -- 列表元素
 -- 顺序列表
 -- 段落标记
 -- 换行和空格保留标记（把所有标记认为是纯文本）
 -- 代表例子（非php）
 -- 无序列表
 -- 代表变量名
特殊用法：
a)    在极少的情况下，用<>来表示
b)    如果需要在docblock中使用’@’符号，需要加上转义符，即用’\@’表示
c)    如果需要在docblock中使用’*/’符号，需要使用’{@*}’
 
 
docblock模板
 
 
从1.2.0版开始，phpDocumentor支持docblock模板功能，模板可以减少大量的重复注释写入，比如，如果很多类成员都是私有成员，你就可以使用docblock模板来标明这些变量都是私有的：
 docblock模板以’/**#@+**/’开头，以’/**#@-*/’结尾
 
 
示例
 
 
一个简单的类
 
 
request = $request;
    }

    /**
     * 执行dispach
     *
     * 根据参数来实现MVC单入口功能，更多ＭＶＣ内容请自行了解
     *
     * @param string $tag 这个是简单描述
     * @return bool 返回运行状态
     */
    public function run( $tag="g" ) {
        /**
         * 状态
         */
        $status = false;
        return  $status;
    }

}
 
 
生成文档
 
 
D:\xampp\php\phpdoc -d untitled1 -t doc
 
 
最后效果：
 
 
 
 
 
  
 
   
 
     
   
 
  
 
  

    BoekGxA.png