来自PHP代码的自动文档

好的，我知道有PhpDocumentor可以从php代码生成文档。看起来它已经很久没有更新了（但也许他们认为它的大部分功能都是完整的）

虽然这可能有助于为其他程序员编写文档，但它似乎不太适合为web服务的外部“API”编写文档。IE，如果我有一个很好的MVC结构化项目，PhpDocumentor可能非常适合记录该项目中的所有模型和内部库等，但是我如何记录它提供的web服务呢

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

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

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

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

我认为您的要求（记录API（尤其是其RESTful）是使用WADL。虽然WADL不会从源代码生成（PHP中没有用于此目的的工具），但WADL非常适合记录服务

您可以拥有各种媒体类型的示例有效负载、所有响应代码以及处理它们的方式，这些都是您真正需要的。

与PhpDocumentor相比，您可能更喜欢DoxyGen（或PHPxRef）

虽然这可能有助于为其他程序员编写文档，但它似乎并不适合为web服务的外部“API”编写文档

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

对每种方法进行说明，并使用

@param[in]

、

@param[out]

和

@return

---

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

那玩意儿很有趣。我将对此进行更深入的研究。我想看看WADL在PHP中使用DocBlock注释所做的事情，以及从这些注释（可能还有WADL文件）生成文档的解析器。我不确定WADL在这里是否正确。WADL似乎更多地是以一种可以用来生成代码的方式定义web服务，而不是相反的方式（带有注释的代码可以生成文档）。我认为真正酷的是一种完全通用的生成器，它可以让你定义你想要的任何标记，并为这些标记提供处理程序。这对于像注释这样的概念会很好地发挥作用，在这些概念中，您正在构建自己的标记类型（即注释对代码和文档生成器都有意义）。我在几个小时前问了几乎相同的问题：），因为我还想为其他程序员（更不用说我自己）记录内部内容……是的，我明白这一点。但是，如果您只为interaces添加注释，然后运行DoxyGen，那么您已经生成了可以提供给其他人的接口文档。这不管用吗？我不知道你所说的仅针对接口的注释是什么意思？如果您的意思是，将控制器方法记录为外部服务调用，将模型记录为内部，这在我的设计中不起作用，因为在任何模型上都有一个通用控制器用于标准CRUD操作，因此唯一需要记录的地方是模型方法（我还使用注释定义模型的db访问权限，等等）.现在我已经坐下来研究这个问题了，我尝试只使用@param标记来记录方法通过web界面接受的POST变量。这里的问题是，phpDocumentor假设这些是该方法的参数，所以文档显示的就是这些参数，这是错误的。我还认为我可以使用@link来显示实际的URL是什么样子的，但是在生成的文档中有点混乱。