顶级类文档答案

【问题标题】：Top-level class documentation顶级类文档
【发布时间】：2016-07-27 05:48:40
【问题描述】：

Rubycop 输出如下消息：

app/controllers/welcome_controller.rb:1:1: C: Missing top-level class documentation comment.
class WelcomeController < ApplicationController
^^^^^

我想知道顶级类文档是什么样的。这不仅仅是评论，是吗？它需要有一种特殊的格式，但是是哪一种呢？

【问题讨论】：

它告诉你，你需要有一个“顶级类”的文档“评论”，在这种情况下是WelcomeController。在类定义上方添加注释以防止出现此消息。可能还有其他方法可以消除此消息。有关详细信息，请参阅rubocop 的文档。
@vee 我尝试在类定义下方添加评论。谢谢。
为了克服添加真实评论的需要，您可以在文件顶部添加#:nodoc:

标签： ruby rubocop

【解决方案1】：

也就是说，像这样的简单评论会很好：

# This shiny device polishes bared foos
class FooBarPolisher
       ...

【讨论】：

为什么这还不是一个被接受的答案？任何寻找答案的人，您也可以查看 rubocop 文档，但请不要禁用检查：rubydoc.info/gems/rubocop/RuboCop/Cop/Style/Documentation
这是最好的答案。

【解决方案2】：

来自the Rubocop documentation：

RuboCop 是一个 Ruby 静态代码分析器。开箱即用，它将强制执行社区Ruby Style Guide 中列出的许多准则。

Ruby 样式指南的“注释”部分没有使用“缺少顶级类文档注释”这一短语，但通过阅读有关 cmets 的指南部分，您可以从示例中快速推断出建议使用注释类和模块。

原因是，当使用rdoc 时，类/模块的 cmets 将用于生成对代码的引用，无论您是为自己、团队还是一般人编写代码，这一点都很重要被其他人释放。

【讨论】：

【解决方案3】：

我最终在这里寻找一种禁用此检查的方法，如果这是您的情况，请输入

Documentation:
  Enabled: false

在您的 .rubocop.yml 文件中。

【讨论】：

它给出了Warning: no department given for Documentation. 错误。必须是Style/Documentation: Enabled: false
我认为我们不应该禁用检查，因为我们正在我们的应用程序中添加 Rubocop 以实施最佳实践。它可以像添加单行一样简单，可以描述特定类在 lab419 中所做的事情：stackoverflow.com/a/38218293/9359123
@PrabinPoudel 这取决于您的团队的决定：您应该配置 rubocop 以仅实施您在项目中发现需要的那些实践，因为我们应用的每个良好实践在应用它们时也会带来时间成本, 有些比其他的多。此外，Clean Code 指出在自我解释代码中应避免使用 cmets，除非您正在开发 api。像“用户”这样的几个类有时可以很好地理解，而不需要对它们进行不必要的评论，比如“应用程序用户的模型”。但同样，这取决于您：根据您的需要配置 rubocop。
我同意。这就说得通了。我的意思是在这个特定的上下文中，提出问题的人想知道应该如何将评论添加到特定的类中。就我个人而言，我来这里是为了寻找修复错误，并找到了这个答案，因为我想修复错误而不是禁用检查，所以我觉得这很误导。但这取决于您提到的团队决定。如果一个答案在对提出问题的用户有用时被接受，则可以避免这种情况。
哦，我明白了。当然，lab419 的回答将是 DreamWalker 问题的最佳答案。我只添加了如何禁用检查，因为正如我所说：我最终在这里寻找一种方法来做到这一点，由于缺少答案，我不得不即兴发挥。回来补充吧。