Geek asks and answers

Documenting I / O with Doxygen or PHPDoc

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

So, I started learning Doxygen with the hope that it would provide me with a better way to document all of these variables. My code includes many AJAX requests, so most variables are sent via mail.

Is there a good way to document post variables in doxygen? I am having trouble determining if I will receive an error message with only the standard parameter tag.

If not, is there another document that may be useful in this process? Or should I just manually document everything and ignore the search for an automatic documentary tool?

Thank!

+5
source share
1 answer

If methods read them directly from $ _POST, and not as method arguments, then I would rely on the @uses tag in the docblock method:

/**
 * 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 understand that the keyword "global" is not technically necessary for the superglobal inside the method, but it helps to document it.

Edit

Please note that according to the reference guide, PHPDoc @uses is intended to display bilateral relationships.

Documentation generators MUST create an @ used-by tag in the documentation of the receiving element that references the element associated with the @uses tag

, semantically @uses , @see $_ [POST | GET | REQUEST ]. / , @see FQSEN, doc

+4

More articles:


All Articles