Agregar documentación para los ámbitos del modelo en rieles

Question

No estoy seguro si esto es realmente posible o no, pero estoy tratando de completar la documentación de nuestra aplicación de rieles agregando documentación para los ámbitos en nuestros archivos app/models. Lo que estoy buscando para tratar de hacer es:

# This is a description of what the scope does and the action that it performs 
scope :newest_records, order("created_at desc").limit(50) 

Y luego cuando corro rdoc sobre la aplicación que quiero para ver newest_records aparece como un método de clase pública junto con los métodos más tradicionales que quedar documentados como:

# some more documentation about this method 
def self.a_class method 
    .... 
end 

EDITAR

realizo esta pregunta puede ser un poco ambigua. Así que aquí hay un intento de aclarar: actualmente, cuando trato de agregar una línea de comentarios sobre una declaración scope, NO recibo documentación generada por RDoc para el alcance. Sé que RDoc puede recoger meta métodos/atributos, de lo contrario no mostraría atributos en los documentos que están declarados con attr_accessor. Así que mi pregunta es ¿cómo puedo añadir comentarios a mi archivo de modo que:

• El método aparece en mi RDoc documentación generada
• Aparece como un método de la clase pública (en contraposición a la instancia pública Método etc)

Answer 1

Después de investigar en los RDoc Docs creo que he podido responder mi propia pregunta.

puede documentar un ámbito de aplicación de la siguiente manera:

## 
# :singleton-method: 
# Documentation for the scope to explain what it does 
scope :newest_records, order("created_at desc").limit(50) 

La doble hash se utiliza para recoger los métodos meta-programados, y si va a crear un método de instancia entonces eso es todo lo que necesita. Sin embargo, como el alcance crea un método de clase, también necesita usar la línea: singleton-method: para indicar eso. La documentación continúa como normal en las siguientes líneas.

Se puede ver la sintaxis completa para la documentación de los meta-métodos, etc. en el RDoc Documentation

Answer 2

Los ámbitos son métodos de clase, por lo que Rdoc lo está haciendo bien. Yo diría que eso está funcionando por lo que Rdoc sabe.

Es posible que tenga un mejor control con algo más extensible como YARD.