Parece una gran cantidad de bibliotecas/plugins utilice esta sintaxis:¿Por qué es necesaria la sintaxis ": nodoc:"?
def self.included(base) # :nodoc:
base.extend ClassMethods
end
¿Por qué es la parte :nodoc: necesario?
No es necesario. Si se aplica a una clase, simplemente suprime la documentación (rdoc) para todos los métodos en la extensión de Clase. Se describe en programación Ruby como:
: nodoc: - No incluir este elemento en la documentación. Para las clases y los módulos , los métodos, los alias, las constantes y los atributos directamente dentro de la clase afectada o el módulo también se omitirán de la documentación . De forma predeterminada, sin embargo, módulos y clases dentro de esa clase o el módulo estarán documentados.
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 leyendo el código de una libarie y tuve que preguntarme "¿por qué?". No veo ningún motivo para usar esta función. Si no quieres que las personas usen tu método, solo hazlo en privado. Es una gran molestia cuando lee la documentación y ve un método de llamada a un método que no se encuentra en la documentación.
Usted tiene un punto allí. No estoy de acuerdo con que ': nodoc:' nunca pueda ser útil. Pero se usa en exceso, las personas tienden a usarlo para métodos que consideran de alguna manera como "sin importancia", o como una forma de evitar escribir documentación cuando no pueden pensar qué escribir. –
Irónicamente, los métodos que se consideran "sin importancia" suelen ser los que me estoy rascando al pensar "¿por qué hace eso?". Para aquellos ': nodoc:' es un código (¿documentación?) Huele ... –