php - 使用类描述的 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对 docblocks 只字未提。

真正重要的是您的评论被处理的方式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 视为对class Myclass的注释，但不会找到对完整文件的注释。所以生成文档后还是会报错。

但是，对于这两种方法，我会选择第二种，因为最好先有类描述，然后是文件描述。