PSR для использования описания класса

Я не могу найти в PSR ничего, что говорило бы о том, где следует разместить комментарий о классе и пространстве имен. Должно ли это быть первое описание класса или пространства имен?

<?php
/**
 * Some description about this class
 *
 * @author      Mr. Anderson
 * @since       06/09/17
 * @package
 *
 */

namespace MyNamespace;

class MyClass
{
}

Или правильно что?

<?php

namespace MyNamespace;

/**
 * Some description about this class
 *
 * @author      Mr. Anderson
 * @since       06/09/17
 * @package
 *
 */

class MyClass
{
}

php phpdoc psr-2 psr-1
person Timur    schedule 06.09.2017    source источник
comment
PSR не распространяется на phpdoc. Я бы поставил их прямо перед ключевым словом class   -  person apokryfos    schedule 06.09.2017

Ответы (1)


arrow_upward
4
arrow_downward

PSR не имеет к этому никакого отношения. PSR ничего не говорит о докблоках.

Что действительно важно, так это то, как phpdoc обрабатывает ваши комментарии:

<?php
/**
 * Some description about this class
 *
 * @author      Mr. Anderson
 * @since       06/09/17
 * @package
 *
 */

namespace MyNamespace;

class MyClass
{
}

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

Во втором случае:

<?php

namespace MyNamespace;

/**
 * Some description about this class
 *
 * @author      Mr. Anderson
 * @since       06/09/17
 * @package
 *
 */

class MyClass
{
}

phpdoc будет рассматривать докблок как комментарий к классу Myclass, но не найдет комментарий к полному файлу. Таким образом, у вас все равно будет ошибка после создания документов.

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

person u_mulder    schedule 06.09.2017
comment
Как подсказал @u_mulder, phpDocumentor ожидает увидеть оба блок документа на уровне файла (его первый пример) и блок документа на уровне класса (его второй пример)... так что Я предлагаю использовать оба. Если вы хотите конкретно задокументировать само пространство имен, этот докблок должен идти после докблока на уровне файла, перед самой строкой пространства имен. - person ashnazg; 08.09.2017