用Doxygen或PHPDoc记录获取/发布参数 [英] Documenting Get/Post Parameters with Doxygen or PHPDoc

问题描述

我正在浏览PHPDoc的文档，找不到找到将我发送给各种方法的Post变量的好方法。

I was looking through the documentation for PHPDoc and could not find a good way to document the Post variables I was sending to various methods.

因此，我开始希望对Doxygen有所了解，希望它将为我提供记录所有这些变量的更好方法。我的代码涉及很多AJAX请求，因此大多数变量是通过post发送的。

So, I started to look into Doxygen with the hopes that it would provide me with a better way to document all of these variables. My code involves a lot of AJAX requests, so most of the variables are sent through post.

我是否有一个很好的方法来记录doxygen中的post变量？我无法确定仅使用标准参数代码运行是否会出错。

Is there a good way for me to document the post variables in doxygen? I'm having trouble determining whether I'll get an error just running with the standard parameter tag.

如果没有，在此过程中是否还有其他记录员可能会有所帮助？还是我应该手动记录一切，而忽略寻找自动记录工具？

If not, is there another documentor that might be helpful in this process? Or should I just manually document everythign and ignore looking for an automatic documenting tool?

谢谢！

推荐答案

如果方法直接从中读取$ _POST，而不是作为方法参数，然后我要依靠方法的文档块中的@uses 标记：

If the methods are reading those directly from $_POST, rather than as method arguments, then I'd lean on the @uses tag in the method's docblock:

/**
 * My foo() method
 * @return void
 * @uses $_POST['bar'] directly
 */
public function foo()
{
    echo "I use ", $_POST['bar'], "... :-)";
}

另一个选项可能是@global标记：

Another option might be the @global tag:

/**
 * My bar() method
 * @return void
 * @global mixed uses the 'bar' key from the $_POST superglobal directly
 */
public function foo()
{
    global $_POST;
    echo "I use ", $_POST['bar'], "... :-)";
}

我意识到 global关键字在技术上对于内部的超全局变量不是必需的一种方法，但确实有助于将其记录在案。

I realize that the "global" keyword is not technically necessary for a superglobal inside a method, but it does help get it documented.

编辑

请注意，根据PHPDoc的参考指南， @uses 旨在显示双向关系。

Note that according to PHPDoc's reference guide, @uses is intended to show a two-way relationship.

文档生成器应该在接收元素的文档中创建一个@ used-by标记，该标记链接回与@uses相关的元素标签

Documentation generators SHOULD create a @used-by tag in the documentation of the receiving element that links back to the element associated with the @uses tag

因此，尽管在语义上@uses可能读得更好，但 @ see 也可以用来记录$ _ [POST | GET | REQUEST]参数。两者之间的主要/唯一区别是，@ see是指向 FQSEN 在文档块中被引用

Thus, although semantically @uses might read better, @see could also be used to document a $_[POST|GET|REQUEST] parameter. The main/only difference between the two is that @see is meant to be a one-way link to the FQSEN being referenced in the doc block

这篇关于用Doxygen或PHPDoc记录获取/发布参数的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！