Come documentare un'applicazione per le rotaie?

Question

Ho appena iniziato a documentare un'applicazione ferroviaria.So che in realtà questo viene fatto da rdoc, quindi ho seguito alcune guide rdoc riguardanti la sintassi e così via, ma sono rimasto bloccato quando ho provato a descrivere gli attributi dei modelli, le convalide e la relazione tra i modelli, soprattutto perché queste cose fanno parte di ActiveRecord.Quindi mi chiedo se esiste qualche guida o buona pratica su come documentare un'applicazione ferroviaria o se c'è qualcosa che mi sfugge?

So che potrei inserire tutto questo nella descrizione della classe, ma mi chiedo se esiste un modo più strettamente legato alla dichiarazione stessa (has_many, validates_presence_of, ecc.) e per quanto riguarda gli attributi?

Answer 1

Personalmente preferisco YARD - http://yardoc.org , poiché fa un lavoro migliore nel documentare IMHO.Non so se sia disponibile un gestore specifico per Rails, ma è abbastanza semplice scriverne uno - http://yardoc.org/guides/extending-yard/writing-handlers.htmlUn buon esempio potrebbe essere il gestore degli attributi, parte della gemma del cantiere:lib/yard/handlers/ruby/attribute_handler.rb

Answer 2

Ricordate i test sono parte della documentazione (per gli sviluppatori), in particolare se si utilizza Cetriolo, dove gli scenari sono facili da leggere. Se si mantiene i vostri metodi molto breve e non v'è un metodo di test con un nome descrittivo per esempio "Dovrebbe impostare il nome degli utenti" Trovo che in genere non hanno bisogno di commenti sul metodo.

Le convalide o altre parti del Rails non voglio documentare. Parte di essere uno sviluppatore Rails è capire come questi lavori, penso che sia una fiera presupposto che un altro manutentore del codice leggerlo lungo la strada saprà convalide, o altre cose incorporate in Rails. Con la stessa logica, se è possibile utilizzare le caratteristiche dei percorsi di quadro o felici (non si discostano molto) con [documentato] codice di terze parti, un sacco di documentazione sarà scritto per voi.