什么是phpDocumentor

小浩姑娘_8857

小浩姑娘_8857

2016-05-17

1046人浏览

原创

phpdocumentor是一个用php写的工具,对于有规范注释的php程序,它能够快速生成具有相互参照,索引等功能的api文档。

1. 什么是phpDocumentor ?
phpdocumentor是一个用php写的工具,对于有规范注释的php程序,它能够快速生成具有相互参照,索引等功能的api文档。老的版本是 phpdoc,从1.3.0开始,更名为phpDocumentor,新的版本加上了对php5语法的支持,同时,可以通过在客户端浏览器上操作生成文档,文档可以转换为PDF,HTML,CHM几种形式,非常的方便。
PHPDocumentor工作时,会扫描指定目录下面的php源代码,扫描其中的关键字,截取需要分析的注释,然后分析注释中的专用的tag,生成 xml文件,接着根据已经分析完的类和模块的信息,建立相应的索引,生成xml文件,对于生成的xml文件,使用定制的模板输出为指定格式的文件。

2. 安装phpDocumentor
和其他pear下的模块一样,phpDocumentor的安装也分为自动安装和手动安装两种方式,两种方式都非常方便:
a. 通过pear 自动安装
在命令行下输入
pear install PhpDocumentor
b. 手动安装
在http://www.php.cn/下载最新版本的PhpDocumentor(现在是1.4.0),把内容解压即可。


3.怎样使用PhpDocumentor生成文档
命令行方式:
在phpDocumentor所在目录下,输入
Php –h
会得到一个详细的参数表,其中几个重要的参数如下:
-f 要进行分析的文件名,多个文件用逗号隔开
-d 要分析的目录,多个目录用逗号分割
-t 生成的文档的存放路径
-o 输出的文档格式,结构为输出格式:转换器名:模板目录。
例如:phpdoc -o HTML:frames:earthli -f test.php -t docs
Web界面生成
在新的phpdoc中,除了在命令行下生成文档外,还可以在客户端浏览器上操作生成文档,具体方法是先把PhpDocumentor的内容放在apache目录下使得通过浏览器可以访问到,访问后显示如下的界面:

点击files按钮,选择要处理的php文件或文件夹,还可以通过该指定该界面下的Files to ignore来忽略对某些文件的处理。
然后点击output按钮来选择生成文档的存放路径和格式.
最后点击create,phpdocumentor就会自动开始生成文档了,最下方会显示生成的进度及状态,如果成功,会显示

Total Documentation Time: 1 seconds
done
Operation Completed!!
然后,我们就可以通过查看生成的文档了,如果是pdf格式的,名字默认为documentation.pdf。


4.给php代码添加规范的注释
PHPDocument是从你的源代码的注释中生成文档,因此在给你的程序做注释的过程,也就是你编制文档的过程。
从这一点上讲,PHPdoc促使你要养成良好的编程习惯,尽量使用规范,清晰文字为你的程序做注释,同时多多少少也避免了事后编制文档和文档的更新不同步的一些问题。
在phpdocumentor中,注释分为文档性注释和非文档性注释。
所谓文档性注释,是那些放在特定关键字前面的多行注释,特定关键字是指能够被phpdoc分析的关键字,例如class,var等,具体的可参加附录1.
那些没有在关键字前面或者不规范的注释就称作非文档性注释,这些注释将不会被phpdoc所分析,也不会出现在你产生的api文当中。
3.2如何书写文档性注释:
所有的文档性注释都是由/**开始的一个多行注释,在phpDocumentor里称为DocBlock, DocBlock是指软件开发人员编写的关于某个关键字的帮助信息,使得其他人能够通过它知道这个关键字的具体用途,如何使用。 PhpDocumentor规定一个DocBlock包含如下信息:
1. 功能简述区
2. 详细说明区
3. 标记tag
文档性注释的第一行是功能描述区,正文一般是简明扼要地说明这个类,方法或者函数的功能,功能简述的正文在生成的文档中将显示在索引区。功能描述区的内容可以通过一个空行或者 . 来结束
在功能描述区后是一个空行,接着是详细说明区,. 这部分主要是详细说明你的API的功能,用途,如果可能,也可以有用法举例等等。在这部分,你应该着重阐明你的API函数或者方法的通常的用途,用法,并且指明是否是跨平台的(如果涉及到),对于和平台相关的信息,你要和那些通用的信息区别对待,通常的做法是另起一行,然后写出在某个特定平台上的注意事项或者是特别的信息,这些信息应该足够,以便你的读者能够编写相应的测试信息,比如边界条件,参数范围,断点等等。

之后同样是一个空白行,然后是文档的标记tag,指明一些技术上的信息,主要是最主要的是调用参数类型,返回值极其类型,继承关系,相关方法/函数等等。
关于文档标记,详细的请参考第四节:文档标记。
文档注释中还可以使用例如 这样的标签,详细介绍请参考附录二。
下面是一个文档注释的例子

/**
* 函数add,实现两个数的加法
*
* 一个简单的加法计算,函数接受两个数a、b,返回他们的和c
*
* @param int 加数
* @param int 被加数
* @return integer
*/
function Add($a, $b)
{
return $a+$b;
}
生成文档如下:
Add
integer Add( int $a, int $b)
[line 45]
函数add,实现两个数的加法
Constants 一个简单的加法计算,函数接受两个数a、b,返回他们的和c
Parameters
• int $a - 加数
• int $b - 被加数

5.文档标记:
文档标记的使用范围是指该标记可以用来修饰的关键字,或其他文档标记。
所有的文档标记都是在每一行的 * 后面以@开头。如果在一段话的中间出来@的标记,这个标记将会被当做普通内容而被忽略掉。
@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.php.cn/ 百度
@link
类似于license
但还可以通过link指到文档中的任何一个关键字
@name
为关键字指定一个别名。
@package
使用范围:页面级别的-> define,function,include
类级别的->class,var,methods
用于逻辑上将一个或几个关键字分到一组。
@abstrcut
说明当前类是一个抽象类

@param
指明一个函数的参数
@return
指明一个方法或函数的返回指
@static
指明关建字是静态的。
@var
指明变量类型
@version
指明版本信息
@todo
指明应该改进或没有实现的地方
@throws
指明此函数可能抛出的错误异常,极其发生的情况
上面提到过,普通的文档标记标记必须在每行的开头以@标记,除此之外,还有一种标记叫做inline tag,用{@}表示,具体包括以下几种:
{@link}
用法同@link
{@source}
显示一段函数或方法的内容

6.一些注释规范
a.注释必须是
/**
* XXXXXXX
*/
的形式
b.对于引用了全局变量的函数,必须使用glboal标记。
c.对于变量,必须用var标记其类型(int,string,bool...)
d.函数必须通过param和return标记指明其参数和返回值
e.对于出现两次或两次以上的关键字,要通过ingore忽略掉多余的,只保留一个即可
f.调用了其他函数或类的地方,要使用link或其他标记链接到相应的部分,便于文档的阅读。
g.必要的地方使用非文档性注释,提高代码易读性。
h.描述性内容尽量简明扼要,尽可能使用短语而非句子。
i.全局变量,静态变量和常量必须用相应标记说明

7. 总结
phpDocumentor是一个非常强大的文档自动生成工具,利用它可以帮助我们编写规范的注释,生成易于理解,结构清晰的文档,对我们的代码升级,维护,移交等都有非常大的帮助。
关于phpDocumentor更为详细的说明,可以到它的官方网站
http://www.php.cn/查阅

8.附录
附录1:
能够被phpdoc识别的关键字:

Include
Require
include_once
require_once
define
function
global
class

附录2
文档中可以使用的标签






  •  <br>




      附录三:
      一段含有规范注释的php代码
  • <?php  
    /** 
    * Sample File 2, phpDocumentor Quickstart 
    * 
    * This file demonstrates the rich information that can be included in 
    * in-code documentation through DocBlocks and tags. 
    * @author Greg Beaver <cellog@php.net> 
    * @version 1.0 
    * @package sample 
    */ 
    // sample file #1 
    /** 
    * Dummy include value, to demonstrate the parsing power of phpDocumentor 
    */ 
    include_once 'sample3.php'; 
    /** 
    * Special global variable declaration DocBlock 
    * @global integer $GLOBALS['_myvar'] 
    * @name $_myvar 
    */ 
    $GLOBALS['_myvar'] = 6; 
    /** 
    * Constants 
    */ 
    /** 
    * first constant 
    */ 
    define('testing', 6); 
    /** 
    * second constant 
    */ 
    define('anotherconstant', strlen('hello')); 
    /** 
    * A sample function docblock 
    * @global string document the fact that this function uses $_myvar 
    * @staticvar integer $staticvar this is actually what is returned 
    * @param string $param1 name to declare 
    * @param string $param2 value of the name 
    * @return integer 
    */ 
    function firstFunc($param1, $param2 = 'optional') 
    { 
    static $staticvar = 7; 
    global $_myvar; 
    return $staticvar; 
    } 
    /** 
    * The first example class, this is in the same package as the 
    * procedural stuff in the start of the file 
    * @package sample 
    * @subpackage classes 
    */ 
    class myclass { 
    /** 
    * A sample private variable, this can be hidden with the --parseprivate 
    * option 
    * @access private 
    * @var integer|string 
    */ 
    var $firstvar = 6; 
    /** 
    * @link http://www.php.cn/ Example link 
    * @see myclass() 
    * @uses testing, anotherconstant 
    * @var array 
    */ 
    var $secondvar = 
    array( 
    'stuff' => 
    array( 
    6, 
    17, 
    'armadillo' 
    ), 
    testing => anotherconstant 
    ); 
    /** 
    * Constructor sets up {@link $firstvar} 
    */ 
    function myclass() 
    { 
    $this->firstvar = 7; 
    } 
    /** 
    * Return a thingie based on $paramie 
    * @param boolean $paramie 
    * @return integer|babyclass 
    */ 
    function parentfunc($paramie) 
    { 
    if ($paramie) { 
    return 6; 
    } else { 
    return new babyclass; 
    } 
    } 
    } 
    /** 
    * @package sample1 
    */ 
    class babyclass extends myclass { 
    /** 
    * The answer to Life, the Universe and Everything 
    * @var integer 
    */ 
    var $secondvar = 42; 
    /** 
    * Configuration values 
    * @var array 
    */ 
    var $thirdvar; 
    /** 
    * Calls parent constructor, then increments {@link $firstvar} 
    */ 
    function babyclass() 
    { 
    parent::myclass(); 
    $this->firstvar++; 
    } 
    /** 
    * This always returns a myclass 
    * @param ignored $paramie 
    * @return myclass 
    */ 
    function parentfunc($paramie) 
    { 
    return new myclass; 
    } 
    } 
    ?>


    LiblibAI高清放大
    LiblibAI高清放大

    LiblibAI高清放大是一款AI图片处理工具,LiblibAI 推出的 AI 高清放大工作流。

    下载

    php免费学习视频:立即使用
    踏上前端学习之旅,开启通往精通之路!从前端基础到项目实战,循序渐进,一步一个脚印,迈向巅峰!

    相关文章

    PHP速学教程(入门到精通)
    PHP速学教程(入门到精通)

    PHP怎么学习?PHP怎么入门?PHP在哪学?PHP怎么学才快?不用担心,这里为大家提供了PHP速学教程(入门到精通),有需要的小伙伴保存下载就能学习啦!

    下载

    相关标签:

    本站声明:本文内容由网友自发贡献,版权归原作者所有,本站不承担相应法律责任。如您发现有涉嫌抄袭侵权的内容,请联系admin@php.cn

    相关专题

    更多
    Go-Zero API开发使用教程
    Go-Zero API开发使用教程

    本专题聚焦Go-Zero的API开发,拆解.api描述文件的语法结构、路由与分组定义、参数绑定与校验规则,说明统一响应体、JWT鉴权、跨域与接口文档生成的落地方式,并给出网关聚合与接口测试的实践建议。

    2026.11.12

    140

    15

    Go-Zero安装与goctl环境配置教程
    Go-Zero安装与goctl环境配置教程

    本专题围绕Go-Zero的安装与工具链配置展开,讲清Go版本要求、goctl安装方式、代理镜像、protoc依赖与环境变量设置,说明多版本共存、升级回退与CI流水线安装的做法,并整理安装阶段的常见报错与验证步骤。

    2026.11.12

    100

    15

    Go-Zero零基础入门教程
    Go-Zero零基础入门教程

    本专题整理Go-Zero的入门知识,从框架定位、环境准备到跑通第一个API服务,讲清目录分层、配置加载、日志与中间件的基本用法,并对比Gin、Kratos的差异,帮助Go开发者建立整体认知,判断它是否适合当前项目。

    2026.11.12

    80

    15

    Postman身份认证怎么配置
    Postman身份认证怎么配置

    本专题从实际API接口调试场景出发,讲解Postman身份认证的完整配置流程,包括常见认证协议介绍、授权参数设置、访问令牌填写、OAuth 2.0授权及认证失败排查,帮助用户正确完成接口授权与访问验证。

    2026.11.06

    160

    12

    Postman请求头Headers怎么设置
    Postman请求头Headers怎么设置

    围绕Postman HTTP请求头配置展开,讲解Headers选项的具体使用方式,包括Key和Value参数填写、请求头信息添加、常见Header字段设置及请求头修改方法,帮助用户解决接口调试过程中遇到的请求头配置问题。

    2026.11.06

    140

    13

    Postman接口请求发送教程
    Postman接口请求发送教程

    详细介绍Postman接口请求的创建与发送方法,涵盖GET和POST请求、URL配置、请求参数、Headers请求头、Body请求体设置以及响应结果查看,帮助用户掌握Postman接口请求的完整操作流程。

    2026.11.06

    120

    10

    DBeaver怎么导入数据
    DBeaver怎么导入数据

    DBeaver数据导入专题,整理Excel、CSV、SQL、TXT等常见文件的数据导入方法,涵盖目标数据库选择、数据表创建、字段映射、数据类型设置及导入参数配置等操作,帮助用户将本地文件中的数据写入数据库,并了解批量导入、重复数据处理和导入失败等常见问题的解决方法。

    2026.11.05

    120

    12

    DBeaver安全防护教程大全
    DBeaver安全防护教程大全

    DBeaver安全防护专题,围绕数据库连接安全、账号密码保护和访问权限管理展开,整理SSL/TLS加密连接、SSH隧道、数据库凭据保存及证书验证等配置方法,同时介绍敏感信息保护、远程连接风险和高权限账号使用等注意事项,帮助用户提高数据库日常管理的安全性。

    2026.11.05

    100

    12

    DBeaver连接创建与配置教程
    DBeaver连接创建与配置教程

    本专题聚焦DBeaver数据库连接配置与管理,覆盖从新建连接、选择数据库类型到填写连接参数和验证连接的完整流程。针对MySQL、PostgreSQL、SQL Server等常见数据库,整理相应的连接设置方法,并提供驱动缺失、认证失败和连接异常等问题的排查方向。

    2026.11.04

    120

    16

    热门下载

    更多
    网站特效
    /
    网站源码
    /
    网站素材
    /
    前端模板

    精品课程

    更多
    热门推荐
    /
    最新课程
    phpStudy极速入门视频教程
    phpStudy极速入门视频教程

    共6课时 | 54.7万人学习

    独孤九贱(4)_PHP视频教程
    独孤九贱(4)_PHP视频教程

    共89课时 | 134.3万人学习