Question: 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`?

Answer: 
You could maybe use [@uses](http://manual.phpdoc.org/HTMLSmartyConverter/PHP/phpDocumentor/tutorial_tags.uses.pkg.html) to document superglobals
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](https://stackoverflow.com/questions/3899258/phpdoc-how-do-you-document-implicit-input-parameters-such-as-session/3899947#3899947).

**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>