Cómo documentar una aplicación de rieles?

Question

Me acaba de empezar a documentar una aplicación de rieles. Sé que esto se puede hacer a través rdoc, así que seguí algunas guías rdoc con respecto a la sintaxis y así sucesivamente, pero me quedé atrapado cuando trataba de describir los atributos de los modelos, validaciones y la relación entre los modelos, sobre todo porque estas cosas son parte de ActiveRecord. Por eso me pregunto si hay alguna guía o una buena práctica en relación con cómo documentar un raíles de aplicación o si hay algo que me falta?

Yo sé que podría poner todo esto en la descripción de clase, pero me pregunto si hay una manera más ligada a la propia declaración (has_many, validates_presence_of, etc.) y qué pasa con los atributos?

Answer 1

Yo personalmente prefiero YARD - http://yardoc.org , como lo hace un mejor trabajo en la documentación de mi humilde opinión. No sé si hay un controlador específico para los carriles disponibles, pero es bastante fácil de escribir uno - http://yardoc.org/guides/extending-yard/writing-handlers.html Un ejemplo bien podría ser el manejador de atributo - parte de la gema patio: lib / yarda / manipuladores / Ruby / attribute_handler.rb

Answer 2

Recuerde que sus pruebas son parte de la documentación (para desarrolladores), sobre todo si está utilizando pepino, donde los escenarios son fáciles de leer. Si mantiene sus métodos muy corto y no hay un método de prueba con un nombre descriptivo, por ejemplo, "Debería establecer el nombre de usuario" Encuentro que normalmente no necesito comentarios sobre el método.

Las validaciones u otras partes de rieles yo no documentar. Parte de ser un desarrollador Rails es entender cómo funcionan, creo que es razonable suponer que otro mantenedor de su código de leerlo en el camino conocerán validaciones, u otras cosas incorporadas en los carriles. Por esa misma lógica, si se puede utilizar características de los caminos marco o felices (no se desvía mucho) con código de terceros [documentado], una gran cantidad de la documentación será escrito para usted.