来自 PHP 代码的自动文档答案

【问题标题】：Automatic documentation from PHP code来自 PHP 代码的自动文档
【发布时间】：2010-01-22 01:41:11
【问题描述】：

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

虽然这可能有助于为其他程序员记录事物，但它似乎不太适合记录 Web 服务的外部“API”。 IE，如果我有一个不错的 MVC 结构化项目，PhpDocumentor 可能非常适合为该项目的其他开发人员记录所有模型和内部库等，但我如何记录它提供的 Web 服务？

我在想你可以使用以下标签记录控制器上的方法：

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

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

在这一点上，我想我将自己实现一些东西，使用 phpdoc 块上的反射（或使用带有附录库的注释）并在应用程序中动态访问文档。

【问题讨论】：

【解决方案1】：

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

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

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

分别描述并使用@param [in]、@param [out]和@return。

这不会达到你想要的吗？还是我错过了什么？

【讨论】：

因为我也想为其他程序员（更不用说我自己）记录内部的东西......
是的，我明白这一点。但是，如果您为交互添加了 cmetsonly，然后运行 DoxyGen，那么您已经生成了可以提供给其他人的界面文档。不行吗？
我不确定您所说的仅用于接口的 cmets 是什么意思？如果您的意思是，将控制器方法记录为外部服务调用，将模型记录为内部，这在我的设计中不起作用，因为在任何模型上都有一个用于标准 CRUD 操作的通用控制器，因此唯一记录的地方是模型方法（我还使用注释来定义模型的数据库访问等）。
现在我已经坐下来处理这个问题，我尝试只使用@param 标签来记录方法通过Web 界面接受的POST 变量。这里的问题是 phpDocumentor 假设这些是该方法的参数，所以这就是文档显示的内容，这是错误的。我还想我可以使用@link 来显示实际 URL 的样子，但它在生成的文档中有点令人困惑。

【解决方案2】：

我认为您的要求（记录 API（特别是如果它的 RESTful））将是使用 WADL。诚然它不会从源代码生成（PHP 中没有工具），但 WADL 非常适合记录服务。

您可以拥有各种媒体类型的示例负载、所有响应代码以及您如何处理它们——实际上是您需要的一切。

【讨论】：

WADL 的东西很有趣。我会对此进行更多研究。我想看看 WADL 在 PHP 中使用 DocBlock cmets 所做的事情，以及从这些文件（也可能是 WADL 文件）生成文档的解析器。
我不确定 WADL 是否正确。 WADL 似乎更多地是以一种可用于生成代码的方式定义 Web 服务，而不是相反（带有可生成文档的 cmets 的代码）。我认为真正酷的是某种完全通用的生成器，它可以让你定义你想要的任何标签并为它们提供处理程序。这可以很好地与诸如注释之类的概念一起使用，您可以在其中制作自己的标签类型（即，注释对代码和文档生成器都意味着什么）