[Fix] Missing top level class documentation comment Rubocop

Published by Prabin Poudel 2 min read
cover: [Fix] Missing top level class documentation comment Rubocop
Table of contents

Rubocop is the best way to enforce best practices in our rails project. While working on the project with rubocop enabled, it’s normal to stumble upon the warning: Missing top-level class documentation comment. [Style/Documentation]. When this happens, we have three options to fix or disable the warning.

Warning

  • Missing top-level class documentation comment. [Style/Documentation]

Options Available for Fix

You can disable or fix this warning using either of the 3 options:

  1. Disable cop in the whole project
  2. Disable cop in only one class
  3. Add comment just above the class declaration

Option 1: Disable cop in the whole project

Most of the classes we use are self describing, meaning as a developer, you can easily make sense of what the class is doing. Normally I find this rule not very useful, so most of the time I disable it in the whole project. Add the following cop to your configuration file to disable it project wide:

# .rubocop.yml

Style/Documentation:
  Enabled: false

Option 2: Disable cop in only one class

If you feel this cop is important in your project and don’t want to disable it in the configuration file, then you can disable it in only one class as required.

# app/models/user.rb

# rubocop:disable Style/Documentation
class User
end

Option 3: Add comment just above the class declaration

You can also fix the warning by adding the comment by adding the comment above the class declaration.

# app/models/user.rb

# Service to download ftp files from the server
class FtpService
end

Though this article is specific to resolving Missing top-level class documentation comment. [Style/Documentation], this fix also works on every other warning that rubocop throws.

Did I miss any option that you are using? Let me know in the comments below.

Image Credits: Cover Image by Matt Popovich on Unsplash