¿Por qué la “: nodoc:” sintaxis necesaria?
Pregunta
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:
?
Solución
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.
Otros consejos
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.