Question

是否可以使用phpDocumentor为一些不一定符合其标准的遗留代码生成HTML文档？

我想为旧代码树生成一些初步文档，然后开始改进我的注释并添加适当的@标记，因为我能熟练使用phpDocumentor。我之前从未使用过这个软件，我发现的例子主要集中在如何编写符合其语法的新代码，并使用-f参数生成HTML文件。

我已经通过PEAR命令行安装程序安装了最新的phpDocumentor并在Windows XP上尝试了这个小* .bat文件：

@echo off
phpdoc ^
    --directory "\\server\project\trunk" ^
    --target "C:\tests\project-doc"

...但这就是我得到的：

PHP Version 5.3.5
phpDocumentor version 1.4.3

Parsing configuration file phpDocumentor.ini...
   (found in C:\Archivos de programa\PHP\pear\data/PhpDocumentor/)...

done
Maximum memory usage set at 256M after considering php.ini...
using tokenizer Parser
directory: ''  not found

我也尝试将UNC路径映射到驱动器号：

@echo off
phpdoc ^
    --directory "I:\" ^
    --target "C:\tests\project-doc"

......但是：

PHP Version 5.3.5
phpDocumentor version 1.4.3

Parsing configuration file phpDocumentor.ini...
   (found in C:\Archivos de programa\PHP\pear\data/PhpDocumentor/)...

done
Maximum memory usage set at 256M after considering php.ini...
using tokenizer Parser
a target directory must be specified
 try phpdoc -h

如果我之前创建“C：\ tests \ project-doc”，则此错误消息是相同的。

我的语法出了什么问题？

Answer 1

phpDocumentor确实可以针对“未记录的”代码运行。它基于代码本身构建其文档，并使用docblock作为附加信息（以及@package和@subpackage标记的其他组织）。

我建议从你的现有代码开始使用phpDocumentor，并努力清除你在errors.html文件中看到的警告结果 - 这个文件生成在输出文档的顶层，但是没有从输出文档中链接到它的任何链接。

一旦你清除了那些，就可以开始运行带有-ue参数的phpDocumentor（ - uncocumentedelements），它会向errors.html添加新的警告，突出显示（更详细）仍需要记录的内容。文档块。

现在，至于您尝试针对共享驱动器上的代码运行程序的问题，我不确定那里有什么问题。该脚本显然能够执行PHP并找到phpDocumentor代码本身。您可以尝试将参数放在同一行中，而不是使用^作为换行转义符，并且可能删除路径周围的引号（因为路径中不存在空格）。

Answer 2

我想我已经找到了问题所在。参数解析器非常挑剔，它既不喜欢UNC路径也不喜欢裸根目录。如果我替换它：

--directory "I:\"

......用这个：

--directory "I:\."

......它终于开始运行了。

我想这是一个错误。他们的bug tracker似乎并不公开，所以我不知道这是否是一个已知的问题。

关于遗留代码的phpDocumentor

2 个答案: