是否有记录 GET/POST 参数的标准? [英] Is there a standard for documenting GET/POST parameters?

问题描述

在一个 PHP 项目中，即使主应用程序使用前端控制器逻辑，也可能有很多独立的脚本、ajax 片段等.

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

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

解决方案

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

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

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

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

如果设置了 $POST['foo']，它的值应该总是 {@link BAR_CONST} 或 {@link BAZ_CONST}.

参考文献:

• 内联{@example} -- http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.inlineexample.pkg.html
• 内联 @{link} -- http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.inlinelink.pkg.html

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.

解决方案

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:

• inline {@example} -- http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.inlineexample.pkg.html
• inline @{link} -- http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.inlinelink.pkg.html

这篇关于是否有记录 GET/POST 参数的标准?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！