PhpDoc - how do you document implicit input parameters, such as $_SESSION?

Question

I just wondered what others do.

If a function relies on $_SESSION['some_var'] then the header comment out to make that clear. How do you do it? Just as text, or what?

Or even @param ?

---

Edit: it looks like we settled on @uses ... but what if the fn() "returns" a $_SESSION variable?

What if it "returns" multiple $_SESSION variables?

Answer 1

Wow, I never even thought about that. I don't even doc things like that. I would say to just state it in the method detail like

/**
 * Takes the some_var session variable and uses it to solve world hunger
 * @return food
 */

Makes the most sense to me.

There is @global, but that seems to indicate the creation of a global var. I think @param should only refer to method parameters passed to the method. There is no @note, that I know of.

Answer 2

You could maybe use @uses to document superglobals

Answer 3

@global has two usages: to denote a global var's definition, and to highlight a global's usage in a method. This second usage fits your use case.

However, assuming that you are referencing $_SESSION['some_var'] directly in that method, and never denoting it via the "global" keyword, it's possible that phpDocumentor's @global tag won't find it when the method is parsed. As such, @uses is probably the best alternative as a means to highlight the method's reliance on that superglobal.

[1] -- http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.global.pkg.html