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) { ... }

}

Answer 1

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.