CODEWITHSUNDEEP
phpglobal-variablesphpdoc
AlexV
AlexV

Reputation: 23088

phpDocumentor @global and @name question

First day I use phpDocumentor and so far so good, but I have a question that I didn't catch in the manual... The documentation of global variables.

How would I document this code if:

  1. $someGlobalVar is not decalren in the PHP file of the class (it can even be undelared).
  2. $someGlobalVar is declared like this: $someGlobalVar = array(); (not using the superglobal array like in the phpDocumentor manual).

The PHP code:

class myCustomClass
{
    private $someProperty;

    //I want to document the use of global var in this method
    public function getSomeProperty()
    {
        global $someGlobalVar;

        if (isset($someGlobalVar))
        {
            //...
        }
        else
        {
            //...
        }
    }
}

Edit: I want do document these globals as the manual shows but I'm not sure how/where to put the @global and @name tags.

Edit 2: I ended up using the following snippet just before the declaration of getSomeProperty:

/**
 * Get some property based on the $someGlobalVar global.
 * @global array $someGlobalVar User defined array that bla bla bla.
 * @return mixed Return a result bla bla bla.
 */

I use phpDocumentor syntax so that the NetBeans IDE display inline help in the source code. All seems right in NetBeans but I'm not sure it's the way to do...

Anyone can confirm it's OK?

Upvotes: 2

Views: 1009

Answers (2)

AlexV
AlexV

Reputation: 23088

Since $someGlobalVar is user defined and after some research I think @uses is the most suited way to document this:

@uses $someGlobalVar User defined array that bla bla bla.

From the documentation:

The @uses tag may be used to document any element (global variable, include, page, class, function, define, method, variable)

Upvotes: 1

Stephen Melrose
Stephen Melrose

Reputation: 4830

You would document the variable where it is defined I believe, e.g.

/**
 * My var
 * @var array
 */
$someGlobalVar = array();

You don't need to document it within your class method as you document the API and it's functionality.

My opinion anyway.

Upvotes: 1

Related Questions