来自PHP代码的自动文档

好的，我知道有PhpDocumentor从PHP代码生成文档。看起来它很久没有更新（但也许他们的主要功能已完成）。来自PHP代码的自动文档

虽然这可能对记录其他程序员的事情很好，但它似乎不适合记录Web服务的外部“API”。 IE浏览器，如果我有一个很好的MVC结构化项目，PhpDocumentor可能非常适合记录所有模型和内部库以及该项目的其他开发人员，但是如何记录它提供的Web服务？

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

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

这在生成的文档会显示你需要做一个POST请求时，它会返回JSON数据和访问它的URL是http://whatever.com/device/add。很明显，文档中会有一个全局配置文件，它定义了这些服务调用的基础url。

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

来源

2010-01-22 Greywire

几小时前我问了几乎相同的问题:) http://stackoverflow.com/questions/2121710/is-there-a-standard-for-documenting-get-post-parameters – 2010-01-23 03:00:13

我想你的问题（记录一个API（特别是如果它的RESTful））将使用WADL。授予它不会从源生成（在PHP中没有工具），但WADL非常适合记录服务。

您可以在各种媒体类型，所有响应代码以及您如何处理它们的过程中拥有样本有效载荷 - 您真正需要的一切。

来源

2010-01-22 02:06:47

WADL的东西很有趣。我会更多地考虑这一点。我希望看到WADL在PHP中使用DocBlock注释的一些事情，以及一个从这些（也可能是WADL文件）生成文档的解析器。 – Greywire 2010-01-23 02:56:24

我不确定WADL是否正确。 WADL似乎更多地是以可用于生成代码的方式定义Web服务，而不是其他方式（可以生成文档的注释的代码）。我认为真正酷的是某种完全通用的生成器，它可以让你定义你想要的任何标签并为这些标签提供处理程序。这样可以很好地发挥Annotations这样的概念，你可以在这里构建自己的标签类型（即注释对代码和文档生成器意味着什么） – Greywire 2010-01-23 19:43:19

您可能更喜欢DoxyGen（或PHPxRef）到PhpDocumentor。

“虽然这可能对记录其他程序员的事情很好，但它似乎不适合记录Web服务的外部”API“”。

为什么不把DoxyGen（或其他）的评论只有纳入外部可见的API函数？

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

难道你没有达到你想要的？或者我错过了什么？

来源

2010-01-22 02:36:50 Mawg

因为我也想记录其他程序员的内部东西（更何况我自己）... – Greywire 2010-01-23 19:16:11

是的，我明白这一点。但是，如果您仅为交互操作添加注释*，然后运行DoxyGen，那么您已生成了可供其他人使用的界面文档。会不会工作？ – Mawg 2010-01-24 02:58:16

我不确定你的意思只是为接口提供意见吗？如果您的意思是，将控制器方法记录为外部服务调用，并将模型记录为内部模型，这些方法在我的设计中不起作用，因为在任何模型中都有用于标准CRUD操作的通用控制器，所以文档的唯一位置是模型方法（我也使用注释来定义模型的数据库访问等）。 – Greywire 2010-01-25 21:11:23

来自PHP代码的自动文档

回答

相关问题