首页 php教程 php手册 探讨:如何使用PhpDocumentor生成文档

探讨:如何使用PhpDocumentor生成文档

Jun 13, 2016 am 11:45 AM
phpdocumentor 使用 命令行 如何 探讨 文档 方式 生成

命令行方式:
  在phpDocumentor所在目录下,输入phpdoc –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。
给php代码添加规范的注释

PHPDocument是从你的源代码的注释中生成文档,因此在给你的程序做注释的过程,也就是你编制文档的过程。
  从这一点上讲,PHPdoc促使你要养成良好的编程习惯,尽量使用规范,清晰文字为你的程序做注释,同时多多少少也避免了事后编制文档和文档的更新不同步的一些问题。
  在phpdocumentor中,注释分为文档性注释和非文档性注释。
  所谓文档性注释,是那些放在特定关键字前面的多行注释,特定关键字是指能够被phpdoc分析的关键字,例如class,var等,具体的可参加附录1.
  那些没有在关键字前面或者不规范的注释就称作非文档性注释,这些注释将不会被phpdoc所分析,也不会出现在你产生的api文当中。

如何书写文档性注释:
  所有的文档性注释都是由/**开始的一个多行注释,在phpDocumentor里称为DocBlock, DocBlock是指软件开发人员编写的关于某个关键字的帮助信息,使得其他人能够通过它知道这个关键字的具体用途,如何使用。PhpDocumentor规定一个DocBlock包含如下信息:
1. 功能简述区
2. 详细说明区
3. 标记tag
  文档性注释的第一行是功能描述区,正文一般是简明扼要地说明这个类,方法或者函数的功能,功能简述的正文在生成的文档中将显示在索引区。功能描述区的内容可以通过一个空行或者 . 来结束
  
在功能描述区后是一个空行,接着是详细说明区,. 这部分主要是详细说明你的API的功能,用途,如果可能,也可以有用法举例等等。在这部分,你应该着重阐明你的API函数或者方法的通常的用途,用法,并且指明是否是跨平台的(如果涉及到),对于和平台相关的信息,你要和那些通用的信息区别对待,通常的做法是另起一行,然后写出在某个特定平台上的注意事项或者是特别的信息,这些信息应该足够,以便你的读者能够编写相应的测试信息,比如边界条件,参数范围,断点等等。
  
之后同样是一个空白行,然后是文档的标记tag,指明一些技术上的信息,主要是最主要的是调用参数类型,返回值极其类型,继承关系,相关方法/函数等等。

文档注释中还可以使用例如 这样的标签,详细介绍请参考附录二。<br><strong>一个文档注释的例子<br></strong>/**<br>* 函数add,实现两个数的加法<br>*<br>* 一个简单的加法计算,函数接受两个数a、b,返回他们的和c<br>*<br>* @param int 加数<br>* @param int 被加数<br>* @return integer<br>*/<br>function Add($a, $b)<br>{<br>return $a+$b;<br>}<br>  生成文档如下:<br>Add<br>integer Add( int $a, int $b)<br>[line 45]<br>  函数add,实现两个数的加法<br>Constants 一个简单的加法计算,函数接受两个数a、b,返回他们的和c<br>Parameters<br>• int $a - 加数<br>• int $b - 被加数<br><strong>文档标记:<br></strong>  文档标记的使用范围是指该标记可以用来修饰的关键字,或其他文档标记。<br>  所有的文档标记都是在每一行的 * 后面以@开头。如果在一段话的中间出来@的标记,这个标记将会被当做普通内容而被忽略掉。<br><strong>@access<br></strong>  使用范围:class,function,var,define,module<br>  该标记用于指明关键字的存取权限:private、public或proteced<br><strong>@author<br></strong>  指明作者<br><strong>@copyright<br></strong>  使用范围:class,function,var,define,module,use<br>  指明版权信息<br><strong>@deprecated<br></strong>  使用范围:class,function,var,define,module,constent,global,include<br>  指明不用或者废弃的关键字<br><strong>@example<br></strong>  该标记用于解析一段文件内容,并将他们高亮显示。Phpdoc会试图从该标记给的文件路径中读取文件内容<br><strong>@const<br></strong>  使用范围:define<br>  用来指明php中define的常量<br><strong>@final<br></strong>  使用范围:class,function,var<br>  指明关键字是一个最终的类、方法、属性,禁止派生、修改。<br><strong>@filesource<br></strong>  和example类似,只不过该标记将直接读取当前解析的php文件的内容并显示。<br><strong>@global<br></strong>  指明在此函数中引用的全局变量<br><strong>@ingore<br></strong>  用于在文档中忽略指定的关键字<br><strong>@license<br></strong>  相当于html标签中的<a>,首先是URL,接着是要显示的内容<br>  例如</a><a href="%E2%80%9Dhttp://www.baidu.com%E2%80%9D">百度</a><br>  可以写作 @license http://www.baidu.com 百度<br><strong>@link<br></strong>  类似于license<br>  但还可以通过link指到文档中的任何一个关键字<br><strong>@name<br></strong>  为关键字指定一个别名。<br><strong>@package<br></strong>  使用范围:页面级别的-> define,function,include<br>  类级别的->class,var,methods<br>  用于逻辑上将一个或几个关键字分到一组。<br><strong>@abstrcut<br></strong>  说明当前类是一个抽象类<br><strong>@param<br></strong>  指明一个函数的参数<br><strong>@return<br></strong>  指明一个方法或函数的返回指<br><strong>@static<br></strong>  指明关建字是静态的。<br><strong>@var<br></strong>  指明变量类型<br><strong>@version<br></strong>  指明版本信息<br><strong>@todo<br></strong>  指明应该改进或没有实现的地方<br><strong>@throws<br></strong>  指明此函数可能抛出的错误异常,极其发生的情况<br>  上面提到过,普通的文档标记标记必须在每行的开头以@标记,除此之外,还有一种标记叫做inline tag,用{@}表示,具体包括以下几种:<br>{@link}<br>  用法同@link<br>{@source}<br>显示一段函数或方法的内容

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

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

两个例子:
实例一
实例二

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

热AI工具

Undresser.AI Undress

Undresser.AI Undress

人工智能驱动的应用程序,用于创建逼真的裸体照片

AI Clothes Remover

AI Clothes Remover

用于从照片中去除衣服的在线人工智能工具。

Undress AI Tool

Undress AI Tool

免费脱衣服图片

Clothoff.io

Clothoff.io

AI脱衣机

AI Hentai Generator

AI Hentai Generator

免费生成ai无尽的。

热门文章

R.E.P.O.能量晶体解释及其做什么(黄色晶体)
2 周前 By 尊渡假赌尊渡假赌尊渡假赌
仓库:如何复兴队友
4 周前 By 尊渡假赌尊渡假赌尊渡假赌
Hello Kitty Island冒险:如何获得巨型种子
3 周前 By 尊渡假赌尊渡假赌尊渡假赌

热工具

记事本++7.3.1

记事本++7.3.1

好用且免费的代码编辑器

SublimeText3汉化版

SublimeText3汉化版

中文版,非常好用

禅工作室 13.0.1

禅工作室 13.0.1

功能强大的PHP集成开发环境

Dreamweaver CS6

Dreamweaver CS6

视觉化网页开发工具

SublimeText3 Mac版

SublimeText3 Mac版

神级代码编辑软件(SublimeText3)

crystaldiskmark是什么软件?-crystaldiskmark如何使用? crystaldiskmark是什么软件?-crystaldiskmark如何使用? Mar 18, 2024 pm 02:58 PM

CrystalDiskMark是一款适用于硬盘的小型HDD基准测试工具,可以快速测量顺序和随机读/写速度。接下来就让小编为大家介绍一下CrystalDiskMark,以及crystaldiskmark如何使用吧~一、CrystalDiskMark介绍CrystalDiskMark是一款广泛使用的磁盘性能测试工具,用于评估机械硬盘和固态硬盘(SSD)的读写速度和随机I/O性能。它是一款免费的Windows应用程序,并提供用户友好的界面和各种测试模式来评估硬盘驱动器性能的不同方面,并被广泛用于硬件评

foobar2000怎么下载?-foobar2000怎么使用 foobar2000怎么下载?-foobar2000怎么使用 Mar 18, 2024 am 10:58 AM

foobar2000是一款能随时收听音乐资源的软件,各种音乐无损音质带给你,增强版本的音乐播放器,让你得到更全更舒适的音乐体验,它的设计理念是将电脑端的高级音频播放器移植到手机上,提供更加便捷高效的音乐播放体验,界面设计简洁明了易于使用它采用了极简的设计风格,没有过多的装饰和繁琐的操作能够快速上手,同时还支持多种皮肤和主题,根据自己的喜好进行个性化设置,打造专属的音乐播放器支持多种音频格式的播放,它还支持音频增益功能根据自己的听力情况调整音量大小,避免过大的音量对听力造成损害。接下来就让小编为大

网易邮箱大师怎么用 网易邮箱大师怎么用 Mar 27, 2024 pm 05:32 PM

网易邮箱,作为中国网民广泛使用的一种电子邮箱,一直以来以其稳定、高效的服务赢得了用户的信赖。而网易邮箱大师,则是专为手机用户打造的邮箱软件,它极大地简化了邮件的收发流程,让我们的邮件处理变得更加便捷。那么网易邮箱大师该如何使用,具体又有哪些功能呢,下文中本站小编将为大家带来详细的内容介绍,希望能帮助到大家!首先,您可以在手机应用商店搜索并下载网易邮箱大师应用。在应用宝或百度手机助手中搜索“网易邮箱大师”,然后按照提示进行安装即可。下载安装完成后,我们打开网易邮箱账号并进行登录,登录界面如下图所示

百度网盘app怎么用 百度网盘app怎么用 Mar 27, 2024 pm 06:46 PM

在如今云存储已经成为我们日常生活和工作中不可或缺的一部分。百度网盘作为国内领先的云存储服务之一,凭借其强大的存储功能、高效的传输速度以及便捷的操作体验,赢得了广大用户的青睐。而且无论你是想要备份重要文件、分享资料,还是在线观看视频、听取音乐,百度网盘都能满足你的需求。但是很多用户们可能对百度网盘app的具体使用方法还不了解,那么这篇教程就将为大家详细介绍百度网盘app如何使用,还有疑惑的用户们就快来跟着本文详细了解一下吧!百度云网盘怎么用:一、安装首先,下载并安装百度云软件时,请选择自定义安装选

Word文档在Windows 11/10上打开时为空白 Word文档在Windows 11/10上打开时为空白 Mar 11, 2024 am 09:34 AM

当您在Windows11/10计算机上打开Word文档时遇到空白页面的问题,可能需要进行修复以解决此状况。造成这一问题的根源多种多样,其中最普遍的原因之一是文档本身损坏。此外,Office文件的损坏也可能导致类似的情况。因此,本文提供的修复方法可能会对您有所帮助。您可以尝试使用一些工具来修复损坏的Word文档,或者尝试将文档转换为其他格式再重新打开。另外,检查系统中的Office软件是否需要更新也是解决此问题的一种方法。通过这些简单的步骤,您可能能够解决Word文档空白打开的Word文档在Win

BTCC教学:如何在BTCC交易所绑定使用MetaMask钱包? BTCC教学:如何在BTCC交易所绑定使用MetaMask钱包? Apr 26, 2024 am 09:40 AM

MetaMask(中文也叫小狐狸钱包)是一款免费的、广受好评的加密钱包软件。目前,BTCC已支持绑定MetaMask钱包,绑定后可使用MetaMask钱包进行快速登入,储值、买币等,且首次绑定还可获得20USDT体验金。在BTCCMetaMask钱包教学中,我们将详细介绍如何注册和使用MetaMask,以及如何在BTCC绑定并使用小狐狸钱包。MetaMask钱包是什么?MetaMask小狐狸钱包拥有超过3,000万用户,是当今最受欢迎的加密货币钱包之一。它可免费​​使用,可作为扩充功能安装在网络

通过命令行将Ubuntu 20.04升级到22.04 通过命令行将Ubuntu 20.04升级到22.04 Mar 20, 2024 pm 01:25 PM

本文详细介绍了将Ubuntu20.04升级到22.04的步骤。对于使用Ubuntu20.04的用户,错过了22.04版本带来的新功能和优势。为了获得更好的体验和安全性,建议及时升级到较新的Ubuntu版本。Ubuntu22.04的代号为“杰米水母”,让我们一起来探索如何获取最新的LTS版本吧!如何通过命令行将Ubuntu20.04升级到22.04掌握命令行会给你带来优势。虽然通过GUI更新Ubuntu是可能的,但我们的重点将是通过命令行。首先,让我们使用以下命令检查当前运行的Ubuntu版本:$

小黑盒cdkey如何使用 小黑盒cdkey如何使用 Mar 12, 2024 pm 07:34 PM

如何使用小黑盒cdkey呢?简单来说,您可直接在小黑盒选购Steam平台的游戏,成功购买后将获取一个CDK兑换码。接下来,在Steam商城使用此兑换码即可购得相应游戏。许多朋友可能还不了解如何使用小黑盒cdkey,下面我将为您详细说明其兑换步骤,希望对您有所帮助。小黑盒cdkey如何使用1、先复制购买小黑盒游戏后得到的cdk兑换码。2、随后启动Steam平台。3、点开左上角菜单中的“游戏”选项。4、在新菜单中找到并点击“在Steam上激活产品”。5、在弹出的界面直接点选下一步。6、将小黑盒购买的

See all articles