README

此包为PHPDoc提供对Doxygen的支持。它包含以下内容：

• doxygen-phpdoc-filter.php: Doxygen的输入过滤器，用于解析PHPDoc注释
• Doxyfile.sample: 包含所需选项的Doxygen示例配置文件片段
• doxygen-phpdoc-fixhtml.php: 生成HTML输出的后处理器

它与纯PHPDoc注释配合工作最好。当Doxygen元素混合在一起时，过滤器可能会感到困惑。

安装

该包可以作为独立包安装，也可以作为项目的composer依赖项。

独立包

下载包并使用composer安装其依赖项

cd doxygen-phpdoc
composer install

作为composer依赖项

要将包包含到另一个项目中，请将其添加为依赖项

cd MyProject
composer require --dev hschletz/doxygen-phpdoc

用法

该包提供必须激活在项目的Doxygen配置文件中的输入过滤器。还要激活JAVADOC_AUTOBRIEF选项

FILTER_PATTERNS        = *.php=vendor/bin/doxygen-phpdoc-filter.php
JAVADOC_AUTOBRIEF      = YES

根据需要调整文件扩展名和脚本路径。在配置文件中设置特定于项目的选项后，Doxygen应该能够编译文档。

输出已可用，但有一些限制。后处理器可以修复HTML输出的一些问题。使用输出目录调用它

vendor/bin/doxygen-phpdoc-fixhtml.php doc/api/html

输入过滤器

Doxygen调用输入过滤器，传递源文件名，并处理其输出而不是原始源。输入过滤器的任何修改都是临时的，原始源不会受到影响。

过滤器将文档块内单反斜杠的每个出现视为命名空间分隔符，并用::替换它，这是Doxygen正确操作所必需的。因此，只有PHPDoc的“@”-Syntax才能用于任何标签。连续多个反斜杠保持不变，Doxygen将它们解释为转义反斜杠。

一些PHPDoc标签，如@var、@property、@return或@link，在Doxygen中有不同的含义或语法。这些命令被重写为正确处理的方式。在某些情况下，行为只能在某种程度上模拟。例如，没有@internal的完全等效项，它被替换为@private。同样适用于一些在Doxygen中不存在的命令，如@property-read（将描述放入@remark）或@license（替换为@copyright）。

内联标签，如{@inheritdoc}，在Doxygen中是未知的。去除大括号以防止它们出现在输出中。

文件头被正确标记为文件头。否则，它将被解释为命名空间的文档，这在PHPDoc中是不常见的。

Doxygen 不理解类型化数组，如 string[] 作为参数和返回值的类型。这些将被替换为 array，并在描述中添加完整的类型提示。

HTML后处理器

后处理器会对HTML输出应用一些修正。部分输出为 "::" 的命名空间分隔符在可能的情况下将被转换为反斜杠。一些出现可能仍然存在，因为并非所有这些都能被可靠地检测到。

当使用标签文件帮助链接到内置类的PHP文档时，Doxygen 通过添加.html后缀使链接不可用。这些链接将得到修复。

已知问题

• 尚不支持所有PHPDoc标签。
• 输入过滤器仅在对包含命名空间的文件有效。将来可能添加对无命名空间代码的支持。
• Doxygen 即使对于其他方面正确的代码也会发出一些警告。这些警告可以通过包装脚本过滤掉。

警告：检测到潜在的递归类关系

当类从具有相同名称的不同命名空间继承（直接或间接）时，会出现此消息。这是Doxygen的bug或限制。

警告：内部不一致：类 ... 的作用域未找到！

由于某些未知原因，此消息是由来自标签文件的某些外部文档引起的。

警告：非法命令 ... 作为 <dt> 标签的一部分

这是一个已知的Doxygen bug，当标记为弃用的方法具有参数的命名空间类类型提示时会发生。类型提示将不会在“弃用列表”页面上显示。其他方面文档是正确的。

WARNING：无法解析 ...

此消息是由后处理器在无效的XHTML文件中生成的。无效的标记可能是由不足的转义或不正确格式化的docblocks引起的。检查源文件中的无效语法。