Top-level class documentation

Question

Rubycop outputs messages like:

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

I wonder what does top-level class documentation look like. It's not just a comment, is it? It needs to have a special format, but which one?

It's telling you that you need to have documentation "comment" for a "top-level class" which in this case is `WelcomeController`. Add a comment above the class definition to prevent this message. There may also be other ways to get rid of this message. See documentation for [rubocop](https://github.com/bbatsov/rubocop/) for details. — vee, Apr 06 '16 at 17:12
@vee I tried adding a comment below the class definition. Thanks. — DreamWalker, Apr 06 '16 at 17:17
To overcome the need to add a real comment you could add `#:nodoc:` at the top of the file — Andrey Deineko, Apr 06 '16 at 18:19

score 65 · Answer 1 · edited Nov 14 '21 at 18:36

65

That said a simple comment like so will do nicely:

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

edited Nov 14 '21 at 18:36

answered Jul 06 '16 at 07:20

lab419

1,129
13
16

Why is this not an accepted answer yet? Anyone looking for the answer, you can see the rubocop documentation too, please don't disable the check though: https://www.rubydoc.info/gems/rubocop/RuboCop/Cop/Style/Documentation – Prabin Poudel Aug 19 '20 at 11:54
This is the best answer. – courtsimas Aug 10 '21 at 18:42

score 13 · Answer 2 · edited Nov 14 '21 at 18:36

13

I ended up here looking for a way to disable this check, if that's your case, put

Documentation:
  Enabled: false

in your .rubocop.yml file.

edited Nov 14 '21 at 18:36

answered Jul 04 '19 at 01:29

Alvaro Rodriguez Scelza

3,643
2
32
47

It gives ```Warning: no department given for Documentation.``` error. It needs to be ```Style/Documentation: Enabled: false``` – Semih Arslanoglu Mar 30 '20 at 07:45
I don't think we should disable the check since we are adding Rubocop in our app for implementing best practices. It could be as simple as adding single line that could describe what the particular class is doing like in lab419 answer: https://stackoverflow.com/a/38218293/9359123 – Prabin Poudel Aug 19 '20 at 11:53
2

@PrabinPoudel it is up to what your team decides: you should configure rubocop to implement only those practices you find needed in your project because each good practice we apply also comes with a cost in time when applying them, some more than others. Besides, Clean Code states that comments should be avoided in a self explaining code, unless you are developing an api. Several classes like "User" are sometimes well understood without an unnecessary comment over them that would say something like "Application user´s model". But again, is up to you: configure rubocop as you find fit. – Alvaro Rodriguez Scelza Aug 19 '20 at 20:19
I agree. That makes sense. I meant to say in this particular context, the one who is asking question wants to know how comment should be added to the particular class. Personally I came here searching for fixing the error, and found this answer which I found quite misleading since I wanted to fix the error and not disable the check. But that depends on Team decision like you have mentioned. And this could have been avoided if one answer was accepted when it worked for the user asking the question. – Prabin Poudel Aug 20 '20 at 01:30
Oh I understand. Sure, lab419's answer would be the best one for DreamWalker's question. I only added how to disable the check because as I said: I ended up here looking for a way to do it and since that answer was missing I had to improvise. Came back to add it. – Alvaro Rodriguez Scelza Aug 20 '20 at 08:02

score 9 · Answer 3 · answered Apr 06 '16 at 17:39

From the Rubocop documentation:

RuboCop is a Ruby static code analyzer. Out of the box it will enforce many of the guidelines outlined in the community Ruby Style Guide.

The Ruby Style Guide "comment" section doesn't use the phrase "Missing top-level class documentation comment" but from reading the guide section on comments, you can quickly infer from the examples that commenting classes and modules is recommended.

The reason is, when using rdoc, the comments for the classes/modules will be used to generate the reference to the code, something that is important whether you're writing code for yourself, for a team or for general release by others.

Top-level class documentation

3 Answers3