¿Por qué la “: nodoc:” sintaxis necesaria?

Question

Parece una gran cantidad de bibliotecas / plugins utilizan esta sintaxis:

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

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

Answer 1

No es necesario. Si se aplica a una clase, sólo se suprime la documentación (rdoc) para todos los métodos de la extensión de clase. Se describe en programación Ruby como:

  

nodoc: -   No incluya este elemento en   la documentación. Para las clases y   módulos, los métodos, los alias,   constantes y atributos directamente   dentro de la clase o módulo afectado   También será omitido de la   documentación. Por defecto, sin embargo,   módulos y clases dentro de cada clase   o módulo será documentada.

Answer 2

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

Así que muchas veces he visto que al leer el código de un libarie y tuve que preguntar "¿Por qué?". No veo ninguna razón para utilizar esta característica. Si no desea que la gente a usar su método, simplemente hacerlo privado. Es un gran problema al leer la documentación y ver una llamada de método a un método que queda fuera de la documentación.