Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

How to document a parameter that expects a constant

Tags:

php

phpdoc

What's the recommended way to document function or method parameters whose value is expected to be a predefined constant? So far, I use the data type of the constant and I add a little explanation later.

E.g.:

<?php

class Foo{
    const METHOD_GET = 'get';
    const METHOD_POST = 'post';

    /**
     * Load a new foo
     *
     * @param string $method HTTP method to use (either Foo::METHOD_GET or Foo::METHOD_POST)
     */
    public function load($method=Foo::METHOD_POST){
        // ...
    }

    /**
     * Sort current foo
     *
     * @param int $sort_order Sort order (either SORT_ASC or SORT_DESC)
     */
    public function sort($sort_order=SORT_ASC){
        // ...
    }
}
like image 481
Álvaro González Avatar asked Oct 18 '11 09:10

Álvaro González


1 Answers

Given that you can use a known class as the dataype in param and return tags, I would also expect that you can use a known constant. When you want to specify multiple type options, you just delimit the list with pipes. Modifying your example:

/**
 * Load a new foo
 *
 * @param Foo::METHOD_GET|Foo::METHOD_POST $method HTTP method to use
 */
public function load($method=Foo::METHOD_POST){
    // ...
}

Since the datatype in this case is a known internal-to-the-class value, it might even work without the classname prefix:

* @param METHOD_GET|METHOD_POST $method HTTP method to use
like image 133
ashnazg Avatar answered Sep 21 '22 18:09

ashnazg