18

在 PHP 项目中，即使在主应用程序使用前端控制器逻辑时，也可能存在许多独立脚本、ajax 片段等。

是否有一种标准化的方式——PHPDoc 或其他方式——在脚本的第一个注释块中定义脚本将接受/需要的 GET 和/或 POST 参数以及它们的类型？

我通常通过添加@params 来帮助自己，就好像文件是一个函数一样，并@return解释了脚本的作用和返回，但也许有一种我不知道的更专业的方法。

4

3 回答 3

3

佩卡，

我会考虑使用 WADL 来记录与您的 API 的交互。它没有直接回答您的问题 - 因为这不是从源代码文档、它的 XML 生成的，并且是单独维护的。

它确实直接回答了这个问题：

脚本将接受/需要哪些 GET 和/或 POST 参数以及它们的类型

您可以在文档中放置示例有效负载，以及 URI 参数、接受的内容类型、错误代码/响应/有效负载。我发现它非常有价值，并且使用 WADL，有人可以针对您的 API 编写客户端代码。

更多信息：http ://research.sun.com/techrep/2006/abstract-153.html 和：http ://en.wikipedia.org/wiki/Web_Application_Description_Language

于 2010-01-23T01:47:56.327 回答
3

phpDocumentor 不喜欢文件级文档块中的@param和@return标记...

如果您选择一个单独的文件来记录它们，根据Mr-sk的回答，您可以使用@link指向那里，但它不会立即在您的文件的文档页面中可见......它只是您必须单击才能查看信息的超链接。如果您希望该文件的任何内容在您的脚本文件的文档页面上可见，您可以使用内联{@example}标签指向它，甚至只是其中的某些行，例如{@example /path/ to/file 3 5}只显示第三到第五行。

在这种情况下，我可能会选择仅在文件级文档块的详细描述中进行解释，因为实际上并没有直接的方法将参数标记到 phpDocumentor 无论如何都会将它们识别为代码元素的位置。如果我在描述中使用的任何参数确实是源自代码中其他地方的记录代码元素，我将使用内联{@link}标记指向该代码元素。

例如，假设在另一个代码文件中定义了一些常量，并且在解析其他文件时生成了这些元素自己的文档。如果我在仅脚本文件（如您的文件）的文件级文档块中编写的长描述将这些常量作为参数，那么我的句子可能是：

If $POST['foo'] is set, its value should always be either {@link BAR_CONST} or {@link BAZ_CONST}.

参考：

于 2010-02-01T16:46:45.107 回答
1

我会使用@uses或@see 目前我正在使用@uses，因为它读起来更好并且更有意义

参考：https ://phpdoc.org/docs/latest/references/phpdoc/tags/uses.html

于 2016-05-11T19:36:11.650 回答