Aggiunta di documentazione per gli ambiti del modello nelle guide

Question

Non sono sicuro che sia effettivamente possibile o no, ma sto cercando di rendere più completa la documentazione della nostra app per rotaie aggiungendo la documentazione per gli ambiti nei nostri file app/models. Quello che sto cercando di provare a fare è:

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

E poi quando corro rdoc sopra l'app che voglio vedere newest_records elencato come metodo di classe pubblico insieme con i metodi più tradizionali che andranno documentati come:

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

EDIT

mi rendo conto che questa domanda può essere un po 'ambiguo. Quindi, ecco un tentativo di chiarire: attualmente quando tento di aggiungere una riga di commento sopra una dichiarazione scope, non ottengo la documentazione generata da RDoc per l'ambito. So che RDoc può raccogliere metodi/attributi meta altrimenti non visualizzerebbe attributi nei documenti che sono dichiarati con attr_accessor. Quindi la mia domanda è: come faccio ad aggiungere commenti al mio file in modo che:

• Il metodo appare nel mio RDoc generato documentazione
• Si presenta come un metodo di classe pubblico (in contrapposizione al metodo di istanza pubblica etc)

Answer 1

Dopo un po 'scavare intorno nella documentazione rdoc penso che sono riuscito a rispondere alla mia domanda.

è possibile documentare un ambito come segue:

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

Il doppio hash viene utilizzato per raccogliere i metodi meta-programmato, e se si sta creando un metodo di istanza, allora questo è tutto ciò che serve. Tuttavia, poiché scope crea un metodo di classe, devi anche usare il metodo: singleton: line per indicarlo. Documentazione continua come normale nelle seguenti righe.

È possibile visualizzare la sintassi completa per la documentazione meta-metodi ecc nella RDoc Documentation

Answer 2

ambiti sono metodi di classe, in modo da rdoc sta facendo bene. Direi che funziona fino a che Rdoc lo sa.

Si potrebbe avere un miglior controllo utilizzando qualcosa di più simile estensibile YARD.