使用Doxygen或PHPDoc记录Get/Post参数

Question

我正在浏览PHPDoc的文档,但找不到一个很好的方法来记录我发送给各种方法的Post变量.

因此,我开始研究Doxygen,希望它能为我提供更好的方法来记录所有这些变量.我的代码涉及很多AJAX请求,因此大多数变量都是通过post发送的.

我有一个很好的方法来记录doxygen中的post变量吗？我在确定运行标准参数标签时是否会出错时遇到问题.

如果没有,是否有另一个文件可能在这个过程中有用？或者我应该只是手动记录每个标志而忽略寻找自动记录工具？

谢谢!

Answer 1

如果这些方法直接从$ _POST中读取,而不是作为方法参数,那么我将依赖方法的docblock中的@uses标记:

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

另一种选择可能是@global标签:

/**
 * 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"关键字对于方法中的超全局而言在技术上并不是必需的,但它确实有助于记录它.

编辑

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

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

因此,虽然语义上@uses可能读得更好,但@see也可用于记录$ _ [POST | GET | REQUEST]参数.两者之间的主要/唯一区别是@see是指在doc块中引用的FQSEN的单向链接