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
{
}
Решение
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 будет рассматривать docblock как комментарий к учебный класс Myclass, но не найдете комментарий к полному файлу. Таким образом, у вас все равно будет ошибка после генерации документов.
Но при обоих подходах я бы выбрал второе, потому что лучше иметь учебный класс описание, затем описание файла.
Другие решения
Других решений пока нет …