是否有记录 GET/POST 参数的标准？
在 PHP 项目中，即使前端控制器逻辑用于主应用程序，也可能存在许多独立脚本、ajax 片段等。
是否有一种标准化的方法（PHPDoc 或其他方法）在脚本的第一个注释块中定义脚本将接受/需要哪些 GET 和/或 POST 参数以及它们的类型？
我通常通过添加 @param 来帮助自己，就好像该文件是一个函数一样，并添加一个 @return 解释脚本的作用和返回内容，但也许有一个更专业的方法我就不知道了。
In a PHP project, even when front controller logic is used for the main application, there can be many stand-alone scripts, ajax snippets and so on.
Is there a standardized way - either PHPDoc or something else - to define in the first comment block of the script what GET and/or POST parameters the script will accept / require and of which type they are?
I usually help myself by just adding @params as if the file were a function, and a @return explanation for what the script does and returns, but maybe there is a more specialized way I do not know of.
如果你对这篇内容有疑问，欢迎到本站社区发帖提问 参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。
绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱，如果其他用户或者作者回复了您的评论，将不能在第一时间通知您！
发布评论
评论（3）
phpDocumentor 不喜欢文件级文档块中的 @param 和 @return 标记...
如果您选择单独的文件来记录它们根据 Mr-sk 的回答，您可以使用 @link 指向那里，但它不会立即在文件的文档页面中可见......它只是一个超链接，您必须单击它才能查看信息。如果您希望该文件的任何内容在脚本文件的文档页面上可见，您可以使用内联 {@example} 标记来指向它，甚至只是其中的某些行，例如 {@example /path/to/file 3 5} 仅显示第三行到第五行。
在这种情况下，我可能会选择只在文件级文档块的长描述中解释内容，因为实际上没有直接的方法将参数标记到 phpDocumentor 无论如何都会将它们识别为代码元素的位置。如果我在描述中使用的任何参数确实是源自代码中其他位置的记录代码元素，我将使用内联 {@link} 标记来指向该代码元素。
例如，假设在另一个代码文件中定义了一些常量，并且在解析该其他文件时会生成这些元素自己的文档。如果我在纯脚本文件（如您的文件）的文件级文档块中编写的长描述将这些常量作为参数，那么我的句子可能是：
If $POST['foo'] is set,其值应始终为 {@link BAR_CONST} 或 {@link BAZ_CONST}。参考文献：
phpDocumentor won't like @param and @return tags in the file-level docblock...
If you choose a separate file to document them in, as per Mr-sk's answer, you can use @link to point there, but it won't be immediately visible in your file's documentation page... it'll just be a hyperlink that you'll have to click to go see the info. If you want any of that file's contents to be visible on the documentation page for your script file, you could use the inline {@example} tag to point to it, or even just certain lines in it, e.g. {@example /path/to/file 3 5} to show only lines three through five.
In this scenario, I'd probably choose to just explain things in the long description of the file-level docblock, since there's not actually a direct way of tagging your parameters to where phpDocumentor will recognize them as code elements anyway. If any of the parameters I used in my descriptions were indeed documented code elements that originate somewhere else in the code, I'd use the inline {@link} tag to point to that code element.
For example, let's say there are some constants defined in another code file, and those elements' own documentation gets generated when that other file is parsed. If my long description that I write in the file-level docblock of a script-only file (like yours) talks about those constants as parameters, then my sentence might be:
If $POST['foo'] is set, its value should always be either {@link BAR_CONST} or {@link BAZ_CONST}.References:
Pekka，
我会考虑使用 WADL 来记录与 API 的交互。它没有直接回答您的问题 - 因为这不是从源代码文档及其 XML 生成的，也不是单独维护的。
它确实直接回答了这个问题：
您可以将示例有效负载以及 URI 参数、接受的内容类型、错误代码/响应/有效负载一起放置在文档中。我发现它非常有价值，通过 WADL，有人可以针对您的 API 编写客户端代码。
有关详细信息：http://research.sun.com/techrep/2006/摘要-153.html
以及：http://en.wikipedia.org/wiki/Web_Application_Description_Language
Pekka,
I'd look into using a WADL to document interacting with your API. Its not directly answering your question - because this isn't generated from source code documentation, its XML, and maintained separately.
It does answer this directly:
You can place sample payloads in the document, along with URI params, accepted content-types, error codes/responses/payloads. I find it very valuable, and with a WADL, someone can code a client against your API.
For more info: http://research.sun.com/techrep/2006/abstract-153.html
and: http://en.wikipedia.org/wiki/Web_Application_Description_Language
我会使用
@uses或@see目前我正在使用
@uses因为它读起来更好并且更有意义参考：https://phpdoc.org/docs/latest/references/phpdoc/tags/uses.html
I would use
@usesor@seeCurrently I am using
@usesbecause it reads better and makes senseReference: https://phpdoc.org/docs/latest/references/phpdoc/tags/uses.html