是否有记录GET/POST参数的标准? [英] Is there a standard for documenting GET/POST parameters?
问题描述
在PHP项目中，即使将主控制器逻辑用于主应用程序，也会有许多独立脚本，ajax代码段等.
是否有一种标准化的方法(PHPDoc或其他方法)在脚本的第一个注释块中定义脚本将接受/需要的GET和/或POST参数以及它们的类型?
我通常通过添加@param来帮助自己，就好像文件是一个函数一样，并添加@return解释脚本执行和返回的操作，但是也许还有一种我不知道的更专业的方法.
phpDocumentor不喜欢文件级的 @param 和 @return 标签 docblock ...
根据 Mr-sk 的回答，如果您选择一个单独的文件进行记录，则可以使用 @link 指向该文件，但不会.在文件的文档页面中不会立即可见...它只是一个超链接，您必须单击该超链接才能查看信息.如果您希望脚本文件的文档页面上显示该文件的任何内容，则可以使用内联 {@ example} 标记指向该文件，甚至可以指向其中的某些行，例如 {@ example/path/to/file 3 5} ，仅显示三到五行.
在这种情况下，我可能会选择在文件级docblock的详细描述中进行解释，因为实际上并没有直接的方法将您的参数标记到phpDocumentor会将其识别为代码元素的位置.如果我在描述中使用的任何参数的确是文档代码元素，它们起源于代码中的其他位置，则可以使用内嵌的 {@ link} 标记指向该代码元素.
例如，假设在另一个代码文件中定义了一些常量，并且在解析另一个文件时会生成这些元素自己的文档.如果我在仅脚本文件(如您的文件)的文件级docblock中编写的详细说明谈到了这些常量作为参数，那么我的句子可能是:
If $POST['foo'] is set, its value should always be either {@link BAR_CONST} or {@link BAZ_CONST}.
参考文献:
- 内联 {@ example} - 解决方案
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屋！
