Documenting Get/Post Parameters with Doxygen or PHPDoc [closed]

Question

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.

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.

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?

Thanks!

Answer 1

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'], "... :-)";
}

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'], "... :-)";
}

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

---

Edit

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

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

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