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

Question

Я не могу найти ничего, что говорит в 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
{
}

Answer 1

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, но не найдете комментарий к полному файлу. Так что у вас все равно будет ошибка после генерации документов.

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