11

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){
        // ...
    }
}
Álvaro González
  • 142,137
  • 41
  • 261
  • 360
  • looks fine to me as is, though I'd probably would rather have two methods `post()` and `get()` and sortAsc() and `sortDesc()` or make the http request and sorting strategies external objects passable to Foo. – Gordon Oct 18 '11 at 09:03
  • 1
    Here's a discussion on this topic: https://github.com/phpDocumentor/phpDocumentor2/issues/557 – artspb May 05 '16 at 07:57

2 Answers2

6

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
ashnazg
  • 6,558
  • 2
  • 32
  • 39
  • 3
    I've been testing with a couple of IDEs and phpDocumentor itself. Apparently, none of them will do anything special with the param type (such as creating links or feeding the autocomplete list). So I guess there is no standard way to do it and whatever method I choose will do no harm. I'll consider your idea. – Álvaro González Oct 30 '11 at 16:42
4

#1: PHPStorm-only option, available in all PHP versions

While non-canonical, it's currently possible to achieve auto-completion with a list of options for a param inside PHPStorm, in case it's common in your team. It uses the new PHP8 Annotations, but PHP8 is not required - since the objective is just to parse the source and get auto-completion.

Since it's (unfortunately) not part of the official PHPDoc standard, it gets a bit ugly for simple methods since you need a full (and maybe long) extra line to properly document the options, but it's still better than no docs.

See their official post on the topic, but here's an example from the same post:

enter image description here

#2: PHP-wide option, but only from 8.1 up

PHP 8.1 will feature Enums, which are the "official" version of value lists. Enums can be used as the type of a param, and this would solve the same issue we're having, in an official way and that PHPDoc can support without including new syntaxes - and also actually enforcing the param check during runtime! You can see more how that would work in another PHPStorm post (no affiliation at all, I just happened to discover the feature through them, so I'm honoring the source).

igorsantos07
  • 4,456
  • 5
  • 43
  • 62