Документация класса верхнего уровня

Rubycop выводит сообщения типа:

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

Интересно, как выглядит документация класса верхнего уровня. Это не просто комментарий, не так ли? Он должен иметь специальный формат, но какой?

Ответ 1

Тем не менее простой комментарий, подобный этому, будет приятным:

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

НТН

Ответ 2

Из документация в формате rubocop:

RuboCop - это анализатор статического кода Ruby. Из коробки он будет применять многие из рекомендаций, изложенных в сообществе Руководство по стилю Ruby.

В разделе комментариев "Ruby Style Guide" не используется фраза "Отсутствует комментарий к документации по уровню верхнего уровня", но, прочитав раздел руководства по комментариям, вы можете быстро сделать вывод из примеров, в которых рекомендуется комментировать классы и модули.

Причина в том, что при использовании rdoc комментарии для классов/модулей будут использоваться для генерации ссылки на код, что важно, независимо от того, пишете ли вы код для себя, для команды или для общего релиз другими.

Ответ 3

Я попал сюда в поисках способа отключить эту проверку, если это ваш случай, поставить

Документация: Включено: false

в вашем файле .rubocop.yml.