Skip to content

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

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

Цель документирования с помощью PHPDoc — предоставить исчерпывающий, но гибкий способ описания программной системы на максимально детальном уровне. Такой тип документации помогает участникам разработки и потребителям вашего исходного кода, например, понять, какой тип информации необходимо передавать в конкретные методы, или как использовать класс проекта, который потребитель хочет применить.

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

PHPDoc как нотация была впервые представлена в 2000 году Ульфом Венделем, в значительной мере вдохновлена JavaDoc и в настоящее время используется значительной долей публичных PHP-проектов.

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

PHPDocumentor возглавлял и способствовал росту популярности нотации PHPDoc, однако с увеличением числа других инструментов, использующих нотацию PHPDoc, становится всё более важным иметь официальный и формальный стандарт вместо де-факто статуса, который существует на данный момент.

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

  • Разработчики (потребители) имеют общий источник знаний, к которому могут обращаться при работе с PHPDoc.
  • Проекты и их разработчики (участники) имеют авторитетный источник, которым могут руководствоваться.
  • Вендоры IDE могут стандартизировать способ использования PHPDoc для улучшения таких функций, как автодополнение и навигация.
  • Проекты, использующие данные PHPDoc для дополнения своей функциональности, такие как генераторы документации или приложения, использующие аннотации, получат общий язык с их потребителями.
  • Недостающая функциональность может быть описана и реализована упомянутыми заинтересованными сторонами.

Недостатки:

  • Если существуют различные варианты использования элементов нотации PHPDoc, проектам желательно привести их в соответствие с данной спецификацией, что потребует усилий при внедрении.
  • Учитывая возраст текущего стандарта и широкое распространение, невозможно вносить существенные нарушения обратной совместимости с текущими практиками без значительного риска отчуждения существующих пользователей или вендоров.

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

3.1 Цели

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

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

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

4. Подходы

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

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

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

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

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

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

Недостатки:

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

5. Участники

5.1 Редактор

  • Chuck Burgess - PEAR

5.2 Спонсор

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

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

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

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

8. Прошлые участники

Поскольку этот документ является результатом работы многих людей в предыдущие годы, следует признать их вклад:

  • Mike van Riel (предыдущий редактор)
  • Phil Sturgeon (предыдущий спонсор)
  • Donald Gilbert (предыдущий спонсор)
  • Gary Jones (участник)

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