文章/答案/技术大牛

发布

社区首页 >问答首页 >PHPDoc注释，类与文件

问PHPDoc注释，类与文件
EN

Software Engineering用户

提问于 2015-10-07 13:09:56

回答 1查看 4.6K关注 0票数 5

我试图尽可能地标准化我的代码，包括DocComments，使用PHPCS。

PEAR标准似乎包含了两个嗅探，它们要求类和文件DocBlocks中出现几乎完全相同的标记：

PEAR.Commenting.ClassComment
PEAR.Commenting.FileComment

这两个都希望看到这些标记：@category、@package、@author、@license、@link。

----------------------------------------------------------------------
FOUND 10 ERRORS AFFECTING 2 LINES
----------------------------------------------------------------------
  6 | ERROR | Missing @category tag in file comment
  6 | ERROR | Missing @package tag in file comment
  6 | ERROR | Missing @author tag in file comment
  6 | ERROR | Missing @license tag in file comment
  6 | ERROR | Missing @link tag in file comment
 13 | ERROR | Missing @category tag in class comment
 13 | ERROR | Missing @package tag in class comment
 13 | ERROR | Missing @author tag in class comment
 13 | ERROR | Missing @license tag in class comment
 13 | ERROR | Missing @link tag in class comment
----------------------------------------------------------------------

重复这些是很愚蠢的，因为我所有的源文件只包含一个类(或接口或特性)。

我的问题是，哪些标签应该放在哪里。它们都是在文件注释中，还是在类注释中，还是应该在两者之间进行分割。

php

documentation

回答 1

Software Engineering用户

回答已采纳

发布于 2015-10-07 13:09:56

根据我所能找到的，这是我自己的观点，作为我的回答。我真的很想得到这方面的反馈。这个答案是基于一个提议的(不被接受的)标准.

分解：

纵观拟议的PSR-5标准，特别是对每个标签的描述有点帮助。

@类别

不赞成使用@package，因为它做的事情本质上是一样的，所以可以从嗅觉中移除。

@package

可以在任何一种情况下使用，但是在它应用于的文件块中:全局函数、全局常量、全局变量、所需的和包含的。在类中，它应用于类和所有包含元素。假设您的文件只包含一个类，那么@package标记在文件块中就没有意义了。

@提交人

这可以适用于任何结构元素。这些文档并没有具体帮助回答哪个类的问题，但是，由于文件包含类，我会说这应该出现在包含最广泛的元素(文件注释)中，其他作者会在他们编写的任何子元素中添加一个@author标记。

@许可证

同样，这可以应用于任何结构元素，但适用于所有子元素，因此文件似乎是最合适的。

@link

也反对使用@(请参阅)。

所以：

@见

@see比@link松散，并且可以很高兴地同时应用于文件和类。例如，文件可以引用项目网站，文件可以引用类的文档。

摘要：

所以我认为这个文件大概应该是这样的

<?php
/**
 * FileName.php
 * @author    My Name <email@example.com>
 * @copyright 2015 My Company
 * @license   Licence Name
 * @see       Link to project website
 */

namespace My/Namespace;

use Another/Namespace/Class;

/**
 * Class summary
 * A longer class description
 * @package Vendor/Project
 * @see     Link to class documentation
 */
class MyClass {
    ...
}

票数 7

页面原文内容由Software Engineering提供。腾讯云小微IT领域专用引擎提供翻译支持

原文链接：

https://softwareengineering.stackexchange.com/questions/299240

复制

相似问题

问PHPDoc注释，类与文件
EN

回答 1

Software Engineering用户

分解：

@类别

@package

@提交人

@许可证

@link

@见

摘要：

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐

问PHPDoc注释，类与文件EN

回答 1

Software Engineering用户

分解：

@类别

@package

@提交人

@许可证

@link

@见

摘要：

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐

问PHPDoc注释，类与文件
EN