PHPDoc - Документирование @ param без параметра в функции?

Question

В настоящее время я создаю некоторый phpdoc для спокойного API - и я решил использовать синтаксис @param doc для обозначения обязательных параметров над POST.

Однако после генерации phpdoc я заметил, что он отказывается перечислять эти параметры, если они не совпадают точно с входными переменными в самом методе.

@uses и @see не выглядят хорошо и не имеют особого смысла, когда дело доходит до вывода phpdoc. Стиль / внешний вид документа идеально сочетаются с функциональностью @param.

Есть ли способ переопределить правила, установленные PHPDoc, и позволить ему генерировать блоки @param в документации, даже если param не существует в самом методе?

Answer 1

Я полагаю, что вы можете использовать тот же подход для документирования виртуальных методов, что и обходной путь, то есть с помощью записи @method в заголовке phpDoc для класса.

Например:

/**
 * ... 
 *
 * @method mixed remove(integer $pricing_group_id) Remove a group and return a JSON array with remaining groups.
 */
class YourClass {

   ...

   // see class header for phpdoc entry
    public function remove($pricing_group = null) {
        ....
    }

}

Недостатком является то, что (насколько мне известно) этот подход не обеспечивает средства для ввода явных записей описания для параметров метода и возвращаемого значения.

Answer 2

Хорошо, я собираюсь ответить на это с помощью решения, которое я нашел - я ценю все ответы «не делай этого», но все же надеюсь, что кому-то, кто окажется в такой же ситуации, что и я сам », это нужно должно быть сделано немедленно, без изменения формата, и мы не можем выделить на это время ", которое будет полезно в будущем.

Вы можете продолжать использовать синтаксис @param, если инициализируете метод с указанным параметром и просто установите его в null - убедитесь, что он не прерывает существующие вызовы.

/**
* Remove a group
*
* @param int $pricing_group_id Required
* @return mixed JSON array with remaining groups
*/
public function remove($pricing_group = null) {
    ....
}

Ваш вывод PHPDoc теперь будет отображать тип параметра, имя и описание как обычно.

Имейте в виду, что это нехорошая практика и даже не очень правильная практика. Но это будет работать до тех пор, пока вы не сможете убедить вышестоящих сотрудников выделить достаточно времени для перестройки существующей документации на более подходящей платформе.

Answer 3

Если вы хотите документировать свой API, я предлагаю вам использовать подходящие инструменты, такие как API Blueprint или Open API Spec .

И, используя Swagger , вы даже можете использовать аннотации (что, по-видимому, вам и нужно), чтобы документировать API и, в свою очередь, генерировать из него документацию.

Просто не используйте для этого PHPdoc, потому что это просто смешивает понятия.

Answer 4

Возможно, вы захотите использовать «пользовательский» тег, возможно, @parameter, чтобы он отображался «как есть». Вы не получите такое же поведение гиперссылок для имен классов, как у тега param, но вы не будете ограничены отсутствием параметров в самой подписи кода. Возможно, используйте встроенный тег ссылки в описании параметра, который указывает на тип класса параметра. В противном случае обычные теги use, see или link могут находиться в отдельных строках в виде удобных ссылок на классы, являющиеся типами ваших параметров.

В настоящее время нет способа отключить внутреннее поведение логики «фактическая переопределение подписи кода в тегах параметров».

Answer 5

Вы можете сделать это, используя «опционально». IE:

@param string $variable (optional) Blah.

См. Другие примеры на https://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.param.pkg.html.

Используется в том случае, когда параметр является необязательным, неограниченные параметры и т. Д.