Skip to content

Мета-документ тегов PHPDoc

1. Краткое описание

Цель данного PSR — задокументировать (в стиле каталога) де-факто список тегов, исторически используемых в PHP-сообществе.

2. Зачем это нужно?

Мы хотим надлежащим образом стандартизировать де-факто использование тегов как документации к коду.

3. Область применения

3.1 Цели

  • Предоставить полное техническое определение, или схему, стандартных тегов нотации PHPDoc.
  • Ввести новые концепции, соответствующие лучшим практикам или паттернам проектирования, применяемым сегодня.

3.2 Не входит в область применения

  • Данный PSR не даёт рекомендаций о том, как и когда использовать описанные в этом документе концепции, поэтому он не является стандартом кодирования.

4. Подходы

4.1 Выбранный подход

Мы решили формализовать существующие практики, рассмотреть незадокументированные варианты использования (такие как аннотации в стиле Doctrine) и учесть запросы на новые функции генераторов документации (таких как phpDocumentor).

Совокупность перечисленного должна быть описана с достаточной степенью детализации, чтобы снизить количество возможных интерпретаций.

В дополнение к вышесказанному, авторы позаботились о возможности будущих расширений и добавления тегов, которые не затрагивают синтаксис самого PHPDoc.

Преимущества:

  • Предоставляет машиночитаемую и верифицируемую спецификацию.
  • Взвешенное предложение благодаря учёту большого числа факторов.

Недостатки:

  • Технически сложное и многословное.
  • Может быть расширено только при условии, что синтаксис не затрагивается.

5. Участники

5.1 Редактор

  • Chuck Burgess - PEAR

5.2 Спонсор

  • Michael Cullum

5.3 Члены рабочей группы

6. Голосования

7. Ссылки по теме

Большинство соответствующих ссылок упомянуты в самом PSR в качестве обоснования отдельных глав.

Примечание: Порядок убывающий хронологический.