ruby - ¿Por qué se necesita la sintaxis “: nodoc:”?

rdoc

Question

Parece que muchas bibliotecas / complementos usan esta sintaxis:

  def self.included(base) # :nodoc:
    base.extend ClassMethods
  end

¿Por qué es la :nodoc: parte necesaria?

Answer 1

No creo que sea necesario. En realidad, en mi opinión, es una de las características más inútiles de RDoc.

Tantas veces lo he visto mientras leía el código de un libarie y tuve que preguntarme "¿Por qué?". No veo ninguna razón para usar esta función. Si no quieres que la gente use tu método, solo hazlo privado. Es una gran molestia cuando se lee la documentación y se ve una llamada a un método que queda fuera de la documentación.

Answer 2

No es necesario. Si se aplica a una clase, simplemente suprime la documentación (rdoc) para todos los métodos en la extensión Class. Descrito en Programación Ruby como:

: nodoc: - No incluya este elemento en la documentación. Para las clases y los módulos, los métodos, alias, constantes y atributos directamente dentro de la clase o módulo afectado también se omitirán de la documentación. Sin embargo, por defecto, los módulos y las clases dentro de esa clase o módulo serán documentados.