Como documentar um aplicativo Rails?

Question

Comecei a documentar um aplicativo Rails. Eu sei que isso é realmente feito pelo RDOC, então segui alguns guias RDOC sobre sintaxe e assim por diante, mas fiquei preso quando tentei descrever atributos de modelos, validações e a relação entre os modelos, principalmente porque essas coisas fazem parte do ActiveRecord. Então, eu me pergunto se existe algum guia ou uma boa prática sobre como documentar uma aplicação do Rails ou se há algo que estou perdendo?

Sei que poderia colocar tudo isso na descrição da classe, mas me pergunto se há um muito mais intimamente ligado à própria declaração (Has_Many, Validate_Presence_Of, etc.) e e os atributos?

Answer 1

Pessoalmente, prefiro o quintal - http://yardoc.org , como faz um trabalho melhor em documentar o IMHO. Não sei se há um manipulador específico para trilhos disponíveis, mas é muito fácil escrever um - http://yardoc.org/guides/extending-yard/writing-handlers.htmlUm bom exemplo pode ser o manipulador de atributos - parte do quintal GEM: lib/quintal/manipuladores/ruby/attribption_handler.rb

Answer 2

Lembre -se de que seus testes fazem parte da documentação (para desenvolvedores), principalmente se você estiver usando o pepino onde os cenários são fáceis de ler. Se você manter seus métodos muito curtos e existe um método de teste com um nome descritivo, por exemplo, "deve definir o nome do usuário" Acho que normalmente não preciso de comentários sobre o método.

Valitações ou outras partes dos trilhos que eu não documentaria. Parte de ser um desenvolvedor da Rails está entendendo como isso funciona, acho que é uma suposição justa que outro mantenedor do seu código lê -lo no caminho conhecerá as validações ou outras coisas incorporadas aos trilhos. Na mesma lógica, se você puder usar os recursos da estrutura ou caminhos felizes (não se desviarem muito) com o código de terceiros [documentado], grande parte da documentação será gravada para você.