Um eine Softwaredokumentation für Ruby bzw. Ruby on Rails Projekte zu erstellen, gibt es viele Wege. Einerseits mittels Rdoc oder auch mit YARD, welches mir erlaubt, Metadaten in meiner Dokumentation zu setzen.
Dass die Dokumentation des eigenen Quelltextes wichtig ist, brauche ich hier wahrscheinlich nicht mehr erwähnen. Wozu dient die von mir geschriebene Methode bis hin zu einer Installationsdokumentation für neue Entwickler im Team.
Wenn man das Rails-Gem installiert, wird hier die Rdoc-Doku mitgeliefert. Dies erkennt man bei dem Output von gem install rails
:
Installing RDoc documentation for ...
Um die Dokumentation offline zu betrachten, müsst ihr hierfür einfach in der Konsole gem server
eingeben und es startet ein RDoc Server, welchen ihr über http://localhost:8808/ erreichen könnt. Hier sind alle installieren Gems mit ihrer Doku aufgelistet.
Nun aber zu YARD. YARD ist ein alternatives Ruby Dokumentationstool, unterstützt auch die Dokumentationssyntax von RDoc und bietet noch einige zusätliche Tags. Zuerst installiert ihr euch YARD über RubyGems: gem install yard
. Einen Überblick über die YARD-Kommandos erhaltet ihr mit yard --help
. Ähnlich wie bei Rdoc könnt ihr mit yard server --reload
einen lokalen Dokumentenserver starten. Mit –reload werden Änderungen in der Code Dokumentation sofort angezeigt, ohne den Server neu starten zu müssen. Positiv finde ich hier die Gestaltung der Dokumentation. Alles ist sehr übersichtlich und die interaktive Suche ermöglicht es, schnell bestimmte Methoden / Klassen zu finden. Alternativ dazu könnt ihr natürlich auch die Doku in HTML-Dateien mit yard doc
rausrendern.
So neben dem schönen Design der Doku gibt es natürlich noch mehr was YARD kann. In der Dokumentation lassen sich sogenannte “tags” definieren. Diese starten mit einem @ und eine Übersicht über alle YARD-Tags findet ihr hier. Die wichtigsten hier wären @param
und @return
.
Mit @param
kann dokumentiert werden, welche Parameter meiner Funktion / Methode übergeben werden. In eckigen Klammern steht der Typ und danach kann optional noch eine Beschreibung angegeben werden.
# @param [String] the URL of the page to download
Weitere Parameter können einfach mit einer weiteren Zeile angeführt werden.
Mit @return wird der Rückgabewert dokumentiert. Ebenso wie bei @param wird hier der Typ und eine optionale Beschreibung angeben.
Die Tagliste und die gute Präsentation der Dokumentation haben mich dazu bewegt, YARD als Dokumentationstool für meine Ruby on Rails Projekte zu verwenden. Verschiedene YARD-Dokumentationen von Gems findet ihr auf http://rubydoc.org/. Hier könnt ihr auch über “Add project” eine Dokumentation für euer, auf github gehostetes Projekt, erzeugen.