Documenting implicit input parameters such as $_SESSION

If a function relies on $_S开发者_JAVA技巧ESSION['some_var'] then the header comment out to make that clear. How do you do it? Just as text, or what?

Or even @param?

You could maybe use @uses to document superglobals

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.

@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

If your code depends on something global, or external, to be present in order to work (for example, it requires the sqlite to be installed) you can use @use as Nev mentioned.

HOWEVER...

In general, I would say it is a bad practice to have a function populate or use global variables (or use superglobals), as it breaks the encapsulation of the function and creates a strong dependency between the code inside the function and outside.

If any code external to the function is supposed to create or access those globals, the values should instead be passed as parameters to the function.

For example, instead of

function doMagic(){
    if ($_SESSION['use_black_magic'] == true){ // var coming from the outside
      $_SESSION['magic_results'] = 'dead chicken';
    }else{
      $_SESSION['magic_results'] = 'unicorn';
    }
}

$_SESSION['use_black_magic'] = false;
doMagic();
echo $_SESSION['magic_results']; // (unicorn) variable set within doMagic()

it should be

function doMagic( $use_black_magic = true ){
    if ($use_black_magic == true){
      return 'dead chicken';
    }else{
      return 'unicorn';
    }
}

$magic_results = doMagic( false );
echo $magic_results; // unicorn

This way, doMagic() doesn't need to know anything about where the results are to be stored, nor where to find the parameter value. And the external code, doesn't need to know that the function doMagic() is doing something with $_SESSION variables.

As soon as your code grows just a little bit, maintaining, sharing, debugging, and extending this kind of code becomes a nightmare...

• http://en.wikipedia.org/wiki/Separation_of_concerns