php代码文档规范及phpdoc指南-共享版

《php代码文档规范及phpdoc指南-共享版》由会员上传分享，免费在线阅读，更多相关内容在行业资料-天天文库。

1、《PHP文档规范及phpDoc指南》PHP文档规范及phpDoc指南版本内容作者日期1．0初稿焦琨jkyeah@hotmail.com2012-4第12页《PHP文档规范及phpDoc指南》目录1概述32PHPDoc/phpDocumentor32.1什么是PHPDoc/phpDocumentor32.2phpDocumentor1和phpDocumentor252.3phpDocumentor安装52.3.1pear安装52.3.2phpDocumentor安装63使用phpDocumentor生成文档63.1phpDocumentor使用说明63.2生成指定目录下的文

2、档63.3生成指定文件的文档63.4指定文档标题74PHP注释规范74.1需要特别注意的地方74.2文件、类注释84.3方法注释84.4常用tag标签94.4.1常用tag列表94.4.2@param变量类型列表94.5常用的嵌入式{@tag}用法104.5.1{@link}用法104.5.2{@source}用法104.5.3其他inlinetag114.6用法115参考资料12第12页《PHP文档规范及phpDoc指南》1概述对于一个开发人员，文档总是最感到头疼的事情之一。而且，很可能你对待文档会采取截然不同的2种态度：l当你使用别人的代码库

3、的时候，最希望得到的是它的技术文档，尤其是当时间很紧，而你又不得不硬着头皮去读那些生涩的代码的时候。l当写你自己的程序的时候，最不希望做的事情却是给它编写专门的技术文档，你会以种种理由给自己开脱：我的代码已经足够清晰了，完全不用再为它重新编写文档了……为了解决这个问题，文档工具由此产生。按照规范格式编写代码注释，当代码写完了，技术文档也就完成了。良好的代码注释不仅能够帮助开发人员在编写代码时缕清思路，尽可能避免逻辑bug，而且规范的代码注释还能够使用文档工具直接生成API手册。下面是一个规范的代码注释：/***Commonbaseclassofallphpdocclasse

4、s（简述，用在索引列表中）**AsakindofcommonbaseclassPhpdocObjectholds*configurationvalues(e.g.errorhandling)anddebugging*methods(e.g.introspection()).Itdoesnothaveaconstructor,*soyoucanalwaysinheritigPhpdocclassesfromthis*classwithoutanytrouble.（详细的功能描述）**@authorUlfWendel*@version$Id:PhpdocObject.php,v

5、1.32001/02/1815:29:29uwExp$*@packagePHPDoc（文档标记）*/classPhpdocObject{.....}2PHPDoc/phpDocumentor2.1什么是PHPDoc/phpDocumentorPHPDoc（现在项目名改为了phpDocumentor）是PEAR下面的一个非常优秀的模块，它的目标是实现类似javadoc的功能，可以为你的代码快速生成具有相互参照，索引等功能的API文档。第12页《PHP文档规范及phpDoc指南》目前PHPDoc有3个主要的版本：lPHPDoc：此版本最高到1.0beta，已经停止维护，升级为p

6、hpDocumentor，PHPDoc的官网是http://www.phpdoc.de/，有兴趣的话可以看看。此版本生成的文档格式如下图：lphpDocumentor1：此版本最高到1.4.4，已经升级到phpDocumentor2，目前网上大部分的PHP开源项目都是由此版本工具生成的API手册。官网：http://www.phpdoc.org/，此版本生成的文档格式如下图：lphpDocumentor2：此版本还在升级维护中，目前最高版本是2.0.0alpha1。官网：http://www.phpdoc.org/，此版本生成的文档格式如下图：第12页《PHP文档规范及ph

7、pDoc指南》1.1phpDocumentor1和phpDocumentor2因为最初的版本PHPDoc早已停止维护和升级，本文不再介绍和使用。phpDocumentor从1.4.4直接升到了phpDocumentor2，2比较于1做了如下改变：lHighperformance：更高的性能。优化后的phpDocumentor生成同一个项目的文档，比前一版本最高节省90秒。lTemplateSystem：提供了非常灵活的模板系统，用户可以订制自己的API手册样式。而且也修正了1.4.4非常讨厌的默认iso-8859-