遗留代码上的 phpDocumentor

Question

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

我想为旧代码树生成一些初步文档，然后在我熟练使用 phpDocumentor 时开始改进我的 cmets 并添加适当的 @ 标签。我以前从未使用过这个软件，我发现的示例集中在如何编写符合其语法的新代码并使用 -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 确实可以针对“未记录”的代码运行。它基于代码本身构建其文档，并将文档块用作附加信息（以及附加组织，在 @package 和 @subpackage 标签的情况下）。

我建议从 phpDocumentor 开始针对您现有的代码，并努力清除您在 errors.html 文件中看到的警告 - 该文件是在您的输出文档的顶层生成的，但没有'没有任何来自输出文档的链接。

一旦你清除了这些，你就可以使用 -ue 参数 (--undocumentedelements) 开始运行 phpDocumentor，它会在 errors.html 中添加新的警告，突出显示（更详细地）仍然需要记录的内容文档块。

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

Answer 2

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

--directory "I:\"

...用这个：

--directory "I:\."

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

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