Wie eine Rails-Anwendung zu dokumentieren?

Question

Ich habe gerade angefangen eine Rails-Anwendung zu dokumentieren. Ich weiß, das tatsächlich von rdoc getan wird, so dass ich einige rdoc Führern in Bezug auf Syntax gefolgt und so weiter, aber ich habe stecken, als ich versuchte Attribute von Modellen, Validierungen und die Beziehung zwischen den Modellen zu beschreiben, vor allem, weil diese Dinge Teil von Active sind. So frage ich mich, ob es eine Führung oder eine gute Praxis in Bezug auf, wie eine Anwendung Schienen zu dokumentieren oder wenn es etwas gibt, ich bin fehlt?

Ich weiß, dass ich all dies in der Klassenbeschreibung setzen könnte, aber ich frage mich, ob es eine Möglichkeit, mehr ist eng an die Erklärung gebunden selbst (has_many, validates_presence_of, etc.) und was ist mit den Attributen?

Answer 1

Ich persönlich bevor HOF - http://yardoc.org , da es einen besseren Job macht IMHO bei der Dokumentation. Ich weiß nicht, ob es ein spezifischer Handler für Rails zur Verfügung, aber es ist ganz einfach, einer zu schreiben - http://yardoc.org/guides/extending-yard/writing-handlers.html Ein gutes Beispiel dafür könnte das Attribut-Handler sein - Teil des Hofes gem: lib / yard / Handler / ruby ??/ attribute_handler.rb

Answer 2

Denken Sie daran, Ihre Tests Teil der Dokumentation (für Entwickler) sind, vor allem, wenn Sie Cucumber verwenden, wo Szenarien sind leicht zu lesen. Wenn Sie Ihre Methoden sehr kurz und es ist ein Testverfahren mit einem beschreibenden Namen z.B. „Sollte den Namen des Benutzers festgelegt:“ Ich finde ich nicht brauchen über das Verfahren der Regel tun.

Validierungen oder andere Teile des Rails würde ich nicht dokumentieren. Teil eines Rails-Entwickler zu sein, ist das Verständnis, wie diese funktionieren, denke ich, es eine faire Annahme ist, dass ein anderer Betreuer des Codes es auf dem Weg zu lesen wissen Validierungen oder andere in Rails gebaut Dinge. Mit derselben Logik, wenn Sie Merkmale der Rahmen oder glücklich Pfade (nicht abweichen viel) mit [dokumentiert] Code von Drittanbietern verwendet werden können, wird ein großer Teil der Dokumentation für Sie geschrieben werden.