Как задокументировать параметр, который ожидает константу - PullRequest
Новая
       7

Как задокументировать параметр, который ожидает константу

7 голосов
/ 18 октября 2011

Каков рекомендуемый способ документирования параметров функции или метода, значение которых, как ожидается, будет предопределенной константой?Пока что я использую тип данных константы и позже добавлю небольшое объяснение.

Например: 

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

Ответы [ 2 ]

6 голосов
/ 18 октября 2011

Учитывая, что вы можете использовать известный класс в качестве типа данных в тегах param и return, я бы также ожидал, что вы можете использовать известную константу. Когда вы хотите указать несколько опций типа, вы просто разделяете список трубами. Изменение вашего примера: 

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

Поскольку тип данных в этом случае является известным внутренним для класса значением , он может даже работать без префикса имени класса: 

* @param METHOD_GET|METHOD_POST $method HTTP method to use
0 голосов
/ 18 октября 2011

Здесь расположена информация о том, как документировать константу с использованием phpdoc

const / define означает то же самое в php

...