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?

Answer 1

That said a simple comment like so will do nicely:

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

HTH

Answer 2

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.