PHPDocument初探

20151-phpdocumentor-17-638
很早之前就已经听说过这个自动生成开发文档的工具,类似于java的javadoc,只是很久以来没有用过,这也马上就找工作了,所以就拿来研究一下,主要分为三个过程, 安装过程,使用过程,问题解决过程。

一、安装过程
网上提供了两种安装phpdocument的方式,一种是通过命令行的Pear扩展进行安装,另一种通过直接下载文件进行安装,但是本人选择了pear扩展的方式安装的,所以又涉及到了如何安装pear的过程。
①在Wamp5下安装Pear扩展

下载go-pear.phar(下载地址:http://pear.php.net/go-pear.phar )

将go-pear.phar放在待安装目录下:
我使用的是WAMP集成环境,PHP的目录如下:H:\Wamp\bin\php\php5.3.13
我再PHP目录下建立了一个文件夹PEAR,用来作为PEAR的安装目录,同时把go-pear.phar拷贝到 PEAR目录下,如下图所示:
1

运行命令,安装PEAR
打开CMD,进入PHP目录,执行如下命令:
H:\wamp\bin\php\php5.3.13>php -d phar.require_hash=0 PEAR/go-pear.phar

运行后会提示安装在system还是local,输入Local即可。此后一直输入回车,直到提示是否修改php.ini文件,然后输入”Y“
然后依然是连续输入回车。直到安装完成。

PEAR安装完成后,可以再PHP目录下执行命令: pear list 查看已经安装的Package,如下图所示:

2

————————

注意:

  1. 刚安装完PEAR是没有Mail,PHPUnit,PHPCodeSniffer,这些是我后来装的

  2. 如果运行pear list提示错误,那么可能是没有把pear放到PHP的include_path里,解决方法是:

    首先在PHP.ini文件中,将include_path修改为下图所示的内容:
    3
    然后,重启服务器和PHP,此时查看Phpinfo,查看include_path是否已经被修改了:
    4
    ————————————

此时,我们可以运行 pear install Mail-1.2.0 来安装MAIL Package。

安装完成后,编写一个测试文件index.php,内容如下:

<?php  
require_once("Mail.php");  
?>  

运行后,如果没有报错,说明安装成功了,否则极有可能是你的include_path没有配置正确。
参考网址:http://blog.csdn.net/ruby97/article/details/8868197
②通过Pear扩展来安装PHPDocument
进入dos的php目录(也就是通过 cd 到这个目录)
6

输入pear install -a PhpDocumentor
然后就等待安装成功就OK了。

二、使用方法
PHPDoc有两种使用方法:一种是通过命令生成另一种是通过Web界面来生成。
我个人使用的是通过命令来生成,并且也已经算是实验成功了。
7
例如这个例子中,我是想为我的www/photo这个项目来生成开发文档,并且将它存入D:/phpdoc文件夹下,当然像上面说的具体的命令可以通过phodoc -h来查找。
8

观察生成的文件夹
111
里面有个errors.html这里面记录了在生成文档时发生的错误信息?
222

那么为什么发生这样的信息呢?该如何解决呢?
why?
因为PHPDocument在解析整个项目的时候是通过文件内容并且按照注释去进行解析的,然而这个注释的格式是有要求的,那么具体有什么要求呢?
how?
phpDocumentor parses a DocBlock as a page-level DocBlock if it precedes another DocBlock like this:

/**
 * Page-Level DocBlock example.
 * This DocBlock precedes another DocBlock and will be parsed as the page-level.
 * Put your @package and @subpackage tags here
 * @package pagelevel_package
 */
/**
 * function bluh
 */
function bluh()
{
...
}

A page is documented as a procedural page if it is parsed, regardless of its content (NEW in 1.0).

A class-level DocBlock is any DocBlock that precedes a class definition in a php file.

<?php
/**
 * class bluh
 * class-level DocBlock example.
 * @package applies_to_bluh
 */
class bluh
{
   /**
    * This variable is parsed as part of package applies_to_bluh
    */
   var $foo;

   /**
    * So is this function
    */
   function bar()
   {
   }}
?>

参考网址:http://x1987xiaoxiao-com.iteye.com/blog/870655 http://manual.phpdoc.org/HTMLframesConverter/default/phpDocumentor/tutorial_tags.package.pkg.html

PHPDocument初探
Tags:

发表评论

电子邮件地址不会被公开。 必填项已用*标注