来自PHP代码的自动文档

Posted 2023-02-16

确定，我知道有phpDocumentor用于从php代码生成文档。似乎它已经很长时间没有更新了（但也许他们认为它的大部分功能都已完成）。

虽然这可能适合于为其他程序员编写文档，但是它似乎不太适合文档化Web服务的外部“ API”。 IE，如果我有一个不错的MVC结构化项目，那么PhpDocumentor可能非常适合于记录该模型的所有模型和内部库，对于该项目上的其他开发人员而言，之类的，但是如何记录它提供的Web服务？

我正在考虑可以使用以下标记在控制器上记录方法的内容：

/**
 @service /device/add
 @access POST
 @return JSON 
*/

在生成的文档中将显示您需要执行POST请求，它返回JSON数据，并且访问它的URL为http://whatever.com/device/add。显然，文档的全局配置文件将定义这些服务调用的基本URL。

[此时，我想我将自己通过在phpdoc块上进行反射（或使用带有附录库的注释）来实现一些事情，并使文档可以在应用程序中动态访问。

答案

[您可能更喜欢DoxyGen（或PHPxRef）而不是PhpDocumentor。

“虽然这可能适合于为其他程序员记录事物，但它似乎不太适合于记录Web服务的外部“ API”。

为什么不将DoxyGen（或其他）注释only放入外部可见的API函数中？

给出每个描述并使用@param [in]，@param [out]和@return。

无法达到您想要的目标吗？还是我错过了什么？

另一答案

[我认为您的要求（记录API（尤其是其RESTful））是使用WADL。允许它不会从源生成（PHP中没有用于该工具的工具），但是WADL非常适合用来记录服务。

您可以在各种媒体类型，所有响应代码以及如何使用它们的情况下获得样本有效载荷，这实际上是您所需要的一切。

另一答案

我会签出PHPFUI/InstaDoc。这是一个动态文档查看器。它是开发PHP应用程序的理想选择，因为您拥有当时实际上正在编写的新代码的所有当前文档以及所有旧代码，包括通过Composer引入的代码。它读取当前文件的doc块并动态呈现文档。因此，在签入代码之前，您实际上可以查看所包含的文档。经常查看文档，您会发现问题和可以解决的问题。因此，它使工作流程变得非常好。

InstaDoc可以为大量网站生成静态文件。您可以快速查看实际的PHP源以及该文件的git commits。该文档也是交互式的并且带有标签页，因此您可以仅查看感兴趣的部分，例如公共代码，而不是投影的功能。

使用您的作曲家文件，大约需要5行才能启动和运行InstaDoc。值得2分钟的设置，看看它是否对您有用。