Documenting groups of class constants with phpDocumentor

Question

Let's say I've got a method that has a parameter, whose valid values are declared as class constants (think PGSQL_ASSOC/PGSQL_NUM/PGSQL_BOTH). And there's another method, with a similar parameter, using another set of class constants. Is there a way to describe to phpDocumentor that each set of constants as belonging to a logical group of alternatives? It would be useful to have them documented in groups, and being able to refer to the specific groups in the method documentation. Using docblock templates doesn't cut it, as the template's short description is ignored (adding useless clutter), while the long description of the template is appended to the constant-specific description, resulting in kind-of backwards wording (e.g. "BAR_MODE_1 does this and that. Operation modes for Foo::bar()", instead of "Operation modes for Foo::bar(): BAR_MODE_1 does this and that.").

Example:

class Foo {

    // this group of constants are valid modes for the bar() method
    const BAR_MODE_1 = 1;
    const BAR_MODE_2 = 2;
    const BAR_MODE_3 = 3;

    /**
     * @param int see Foo::BAR_MODE_* constants
     */
    public function bar($mode) { ... }

    // this group of constants are valid modes for the baz() method
    const BAZ_MODE_1 = 1;
    const BAZ_MODE_2 = 2;
    const BAZ_MODE_3 = 3;

    /**
     * @param int see Foo::BAZ_MODE_* constants
     */
    public function baz($mode) { ... }

}

Mike Graf · Accepted Answer · 2011-11-25 15:03:32Z

8

Another style may be to use the PHPDocumentor DocBlock Templates

/**#@+
* This comment applies to each in the block
*
* @var varType 
*/
protected $_var1 = 1;
protected $_var2 = 2;
/**#@-*/

see: http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html#basics.docblock

answered Nov 25, 2011 at 15:03

Mike Graf

5,3474 gold badges48 silver badges60 bronze badges

Sign up to request clarification or add additional context in comments.

2 Comments

lanzz Over a year ago

I have actually mentioned docblock templates in my question, as well as why it's not useful in this case.

Mike Graf Over a year ago

yeah I missed that . However its useful to have this code be here when I google how to do DocBlock templates again ;)

Bjoern · Accepted Answer · 2011-11-11 12:10:36Z

3

First thing which comes to my mind is the @see - Tag, it display a link to the documentation for an element.

/**
 * @param int 
 * @see Foo::BAR_MODE_* constants
 */
public function bar($mode) { ... }

More details can be found here in the manual.

answered Nov 11, 2011 at 12:10

Bjoern

16.3k4 gold badges47 silver badges50 bronze badges

2 Comments

lanzz Over a year ago

This directive only renders a text line in the documentation. I don't see how to even make it a link to the constants section, and in my case the relevant constants are not even defined in the same class as the method, but in a parent class.

lanzz Over a year ago

Actually, @see Foo::BAR_MODE_1 produces a link, but hides the relation to the rest of the BAR_MODE_* constants

Collectives™ on Stack Overflow

Documenting groups of class constants with phpDocumentor

2 Answers 2

2 Comments

2 Comments

Hot Network Questions

Collectives™ on Stack Overflow

2 Answers 2

2 Comments

2 Comments

Related