Documenting implicit input parameters like $ _SESSION

Question

If the function relies on $_SESSION['some_var'], then the header comments on it to make it clear. How do you do it? Like text, or what?

Or even @param?

Answer 1

Perhaps you can use @uses to document superglobals

Answer 2

Wow, I didn’t even think about it. I don’t even know such things. I would say just point it out as a method, like

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

Makes the most sense to me.

@global, var. , @param , . @note, .

Answer 3

@global : var . .

, , $_ SESSION ['some_var'] global, , @global phpDocumentor . , @uses, , .

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

Answer 4

- (, sqlite), @use Nev .

...

, , , ( ), .

- , , , .

,

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()

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

Thus, doMagic () should not know anything about where the results should be stored, and where to find the value of the parameter. And the external code, you do not need to know that the doMagic () function does something with the $ _SESSION variables.

Once your code has grown a bit, supporting, sharing, debugging and distributing such code becomes a nightmare ...

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