Wie dokumentiert man eine Schienenanwendung?

Ich habe gerade begonnen, eine Schienenanwendung zu dokumentieren. Ich weiß, dass dies von rdoc gemacht wird, also habe ich einige rdoc-Anleitungen bezüglich Syntax usw. befolgt, aber ich blieb stecken, wenn ich Attribute von Modellen, Validierungen und die Beziehung zwischen Modellen beschreiben wollte, hauptsächlich weil diese Dinge Teil von ActiveRecord sind. Also frage ich mich, ob es eine Anleitung oder eine gute Praxis gibt, wie man eine Rails-Applikation dokumentiert oder ob mir etwas fehlt.Wie dokumentiert man eine Schienenanwendung?

Ich weiß, dass ich das alles in die Klassenbeschreibung schreiben könnte, aber ich frage mich, ob es einen Weg gibt, der enger an die Deklaration selbst gebunden ist (has_many, validates_presence_of, etc.) und was ist mit den Attributen?

Quelle

2010-11-02 ramontiveros

Ich persönlich bevorzuge YARD - http://yardoc.org, wie es eine bessere Arbeit bei der Dokumentation IMHO tut. Ich weiß nicht, ob es einen bestimmten Handler für Rails gibt, aber es ist ziemlich einfach zu schreiben - http://yardoc.org/guides/extending-yard/writing-handlers.html Ein gutes Beispiel könnte der Attributhandler sein - Teil des Yard Gem: lib/yard/handlers/ruby / attribute_handler .rb

Quelle

2010-11-02 10:37:16 Roman

Ich denke, das ist ein sehr interessanter Ansatz, ich denke, dass das einzige Problem ist, dass es noch ein wenig jung aussieht und eine Lernkurve ausgeprägter als ich erwartet habe, trotzdem denke ich, dass es eine Menge Potential hat. Ich fing sogar an, mir einige nette Features vorzustellen, wie die Datenbank mit Dokumentation aus den Migrationen zu versorgen und dann diese Dokumentation in den Generator zu bringen, auf diese Weise können Sie zwei Fliegen mit einer Klappe schlagen, die Anwendungsdokumentation und die Datenbankdokumentation. – ramontiveros

Denken Sie daran, dass Ihre Tests Teil der Dokumentation (für Entwickler) sind, insbesondere wenn Sie Gurken verwenden, wo Szenarien leicht zu lesen sind. Wenn Sie Ihre Methoden sehr kurz halten, gibt es eine Testmethode mit einem beschreibenden Namen, z. "sollte den Benutzernamen festlegen" Ich finde, dass ich in der Regel keine Kommentare zur Methode benötige.

Validierungen oder andere Teile von Rails würde ich nicht dokumentieren. Ein Teil davon, ein Rails-Entwickler zu sein, ist zu verstehen, wie diese funktionieren, ich denke, es ist eine faire Annahme, dass ein anderer Betreuer Ihres Codes, der es liest, Validierungen oder andere in Rails eingebaute Dinge kennt. Wenn Sie die Funktionen des Frameworks oder die Happy Paths (nicht sehr stark abweichend) mit [dokumentiertem] Code von Drittanbietern nutzen können, wird ein Großteil der Dokumentation für Sie geschrieben.

Quelle

2010-11-07 19:18:19

Ich mag diesen Ansatz, für das Entwicklungsteam, denke ich, wird funktionieren, aber in einigen Fällen brauchen Sie ein Dokument, das nicht unbedingt für einen Entwickler verwendet wird, sondern von einem Typ, der sich eigentlich nicht um den Tests (und müssen nicht). – ramontiveros

Andererseits sind Validierungen selbst für einen Programmierer nicht immer einfach zu interpretieren, zum Beispiel habe ich in meiner Anwendung eine Validierung für einige numerische Attribute, die zwischen -180 und 180 liegen müssen. Dies liegt daran, dass dieses Attribut a repräsentiert Breitenwert und diese Werte können nur in diesem Bereich liegen. Und das ist einfach, ich habe andere Validierungen, die Beziehungen und Restriktionen abstrakter enthalten, selbst wenn ich den Code erneut einlese, ist der Code zum ersten Mal nicht klar. – ramontiveros

Wie dokumentiert man eine Schienenanwendung?

Antwort

Verwandte Themen