ruby - style - Documentación de clase superior

rubocop-rspec

Question

Rubycop produce mensajes como:

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

Me pregunto cómo es la documentación de clase superior. No es solo un comentario, ¿verdad? Necesita tener un formato especial, pero ¿cuál?

Answer 1

De la documentación de Rubocop :

RuboCop es un analizador de código estático Ruby. De inmediato, aplicará muchas de las pautas descritas en la Guía de estilo de Ruby de la comunidad.

La sección de "comentarios" de la Guía de Ruby Style no usa la frase "Falta el comentario de la documentación de la clase superior", pero al leer la sección de la guía sobre los comentarios, puede inferir rápidamente de los ejemplos que se recomienda comentar clases y módulos.

La razón es que, al usar rdoc , los comentarios para las clases / módulos se usarán para generar la referencia al código, algo que es importante ya sea que esté escribiendo el código para usted mismo, para un equipo o para el lanzamiento general por parte de otros.

Answer 2

Dicho esto, un simple comentario así lo hará muy bien:

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

HTH