Блог

Главная - Вопросы по программированию - Официальная ссылка PHPDoc для документирования кода PHP

Официальная ссылка PHPDoc для документирования кода PHP

#php #documentation #phpdoc #code-documentation #phpdocumentor2

#php #Документация #phpdoc #код-документация #phpdocumentor2

Вопрос:

Я нахожусь на пути к обновлению своих проектов до PHP 8.0 . До сих пор в комментариях к коду я использовал @param @return теги and, как в «варианте 1», а не как в «варианте 2».:

Вариант 1:

  • @param string[] ... .
  • @return User[] ... .

Вариант 2:

  • @param array ... .
  • @return array ... .

Хотя, поскольку я не знаю, разрешена ли официально первая форма, я начинаю спрашивать себя, не лучше ли было бы перейти ко второму варианту… Итак, я хотел бы спросить вас: существует ли какая-либо официальная ссылка на PHPDoc для документирования PHP-кодов?

Кроме того, целесообразно ли вообще использовать первый вариант вместо второго? Другими словами: есть ли какие-либо аргументы, говорящие против этого, имея в виду и будущее?

Спасибо вам за уделенное время.

P.S: Я нашел ссылку на phpDocumentor, но у меня такое ощущение, что он не является официальным PHP и (пока) не совместим с PHP 8.0 .

Ответ №1:

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

Сам PHP до версии 8 определяет только синтаксис комментариев https://www.php.net/manual/en/language.basic-syntax.comments.php который не включает в себя никаких @ связанных элементов.

https://www.php.net/manual/en/language.attributes.overview.php Версия 8 PHP вводит атрибуты, которые будут родной заменой аннотаций.

Например https://api-platform.com/docs/core/filters /

PHP до 7.x

 /**
 * @ApiResource(attributes={"filters"={"offer.date_filter"}})
 */
class Offer
{
    // ...
}

Начиная с PHP 8

 #[ApiResource(attributes: ['filters' => ['offer.date_filter']])]
class Offer
{
    // ...
}

Стандарт PSR

PHP FIG определил 2 стандарта PSR (еще не утвержден)

Хотя, поскольку я не знаю, разрешена ли официально первая форма, я начинаю спрашивать себя, не лучше ли переключиться на второй вариант…

Я просто буду придерживаться варианта 1. Это чрезвычайно полезно с точки зрения завершения кода. введите описание изображения здесь

Комментарии:

1. Привет, Себастьян. Спасибо за ваш ответ. Я пересмотрю все ответы через 7 дней. Не могли бы вы немного дополнить то, что вы имели в виду под «с точки зрения завершения кода» ? Кроме того, насколько вам известно, является ли phpDocumentor наиболее используемой платформой документации (например, PHPUnit при тестировании кода)?

2. @dakis, возможно, не столько PHPDocumentator, сколько PSR-5 и PSR-19 (оба все еще в виде черновика) github.com/php-fig/fig-standards/blob/master/proposed /…

3. Чтобы уточнить «с точки зрения завершения кода» : PHPDoc помогает IDE укрепить систему динамических типов PHP. Возвращаемый тип function foo(): array mixed[] по умолчанию равен, но может быть снабжен @return string[] комментариями, чтобы среда IDE сузила этот тип string[] , что, в свою очередь, позволяет улучшить завершение кода. На мой взгляд, это наиболее важный вариант использования PHPDoc, и его следует применять как таковой, когда это возможно (несмотря на версии PHP).

4. @JeroenvanderLaan Да. Я добавил скриншот к своему ответу, изображающий именно это.

5. Себастьян, я изучал PSR-5 и PSR-19. Потрясающе! Именно это я и надеялся выяснить, когда задавал вопрос SO. До сих пор я реализовал некоторые интерфейсы / стандарты PSR, хотя эти я как-то пропустил 🙂 Не могли бы вы, пожалуйста, написать о двух PSR в ответе (например, не только в комментарии)? Еще раз большое вам спасибо. Получайте удовольствие.