php - 来自 PHP 代码的自动文档

Question

好的，我知道有用于从 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 块的反射（或使用带有附录库的注释）并在应用程序中动态访问文档。

score 1 · Accepted Answer

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

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

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

描述每个和使用@param [in],@param [out]和@return。

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

score 0 · Accepted Answer

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

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

2 回答 2