Im letzten Blog-Post haben wir die grundlegenden Eigenschaften und Möglichkeiten gesehen, wie eine Software-Dokumentation mit AsciiDoc erstellt werden kann. Jetzt wollen wir uns im Detail anschauen, welche Möglichkeiten AsciiDoc für die Einbindung von Quellcode in die Dokumentation bietet.
Für die Einbindung von Quellcode stehen in AsciiDoc mehrere Varianten zur Verfügung. Im Wesentlichen kann man zwischen einer Einbindung in den Textfluss, also "inline", und der Einbindung als Block, also mehrere Zeilen, unterscheiden.
Code in Textfluss einfügen
Schauen wir uns zunächst die Einbindung in den Textfluss an.
Dazu wird das Wort, welches als Quellcode herausgestellt werden soll, in das Gravis-Zeichen (oder Backtick `) eingeschlossen:
AsciiDoc:
Die `find`-Methode dient zum Lesen eines Kunden.
Gerendert:
Die find-Methode dient zum Lesen eines Kunden.
Code als Block einfügen
Möchte man Code als Block einfügen, setzt man diesen in Blöcke von vier Punkten (....).
Ein Beispiel dafür könnte wie folgt aussehen:
Hier sieht man auch, dass in der ersten Zeile zunächst in eckigen Klammern eine spezielle Anweisung für die Interpretation des Blocks an Asciidoctor gegeben wird. [source,java] bedeutet, es folgt ein Block mit Quellcode in der Sprache Java. Eine Alternative wäre z. B. [source,xml]. Also Quellcode in der Sprache XML. Mit diesen Informationen kann der verwendete Syntax-Highlighter den Quellcode entsprechend formatiert darstellen und auch die Schlüsselwörter (Keywords) der jeweiligen Sprache hervorheben.
Eine weitere optionale Besonderheit ist die zweite Zeile. Hier wird mit einem Punkt (.) eine Legende (Legend) eingeleitet, also eine Beschreibung oder Überschrift zu dem Code-Block.
Gerendert könnte das dann so dargestellt werden:
Code per Include-Anweisung referenzieren
Eine andere Möglichkeit ist es, mit der Include-Anweisung ganze Quellcode-Dateien einzubinden. Man kann damit den "echten" Quellcode in die Dokumentation einbinden und vermeidet Redundanzen, die schnell veralten können.
Ein Beispiel dafür könnte wie folgt aussehen:
....). Darin folgt allerdings die include-Anweisung und es wird eine konkrete Java-Klasse referenziert. Unter dem Code-Block finden wir hier noch eine weitere Besonderheit. Mit Zahlen in spitzen Klamern (z. B. <1>) kann man auf konkrete Zeilen referenzieren und diese mit zusätzlichen Erläuterungen untermauern. Im eigentlichen Quellcode wird dazu die gleiche Notation in Form eines Kommentars verwendet:public Kunde find(long kdNr) { // <1>Schauen wir uns nun an, wie das ganze dann gerendert ausschauen könnte:
Code-Auszüge mit Tags referenzieren
Da man selten eine komplette Quellcode-Datei in die Dokumentation einfügen möchte, wäre es natürlich äußerst praktisch, man könnte nur einen Auszug referenzieren. Auch das ist mit AsciiDoc möglich. Hierzu kann man in den Quellcode-Kommentaren spezielle Tags einbinden. Dies ist bereits in dem oben dargestellten Quellcode sichtbar. Mit der Anweisung tag::findMethod[] wird das Tag mit der Bezeichnung findMethod eingeleitet und mit end::findMethod[] wird das Ende markiert.
Die Einbindung geschieht dann wie folgt:
Auch hier wird wieder mit der include-Anweisung gearbeitet. Hinter dem Dateinamen wird jetzt allerdings das entsprechende Tag in eckigen Klammern angegeben: [tags=findMethod]
Gerendert ist das dann recht unspektakulär und unterscheidet sich kaum vom obigen Beispiel mit inline-Einbindung:
Fazit
In diesem Artikel haben wir die verschiedenen Möglichkeiten zur Einbindung von Quellcode in AsciiDoc angeschaut. Neben der einfachen Hervorhebung von Quellcode-Wörtern im Fließtext können Code-Blocke eingefügt werden – diese sowohl inline oder als Referenz auf eine Quellcode-Datei, und diese natürlich auch nur auszugsweise. Damit ist die erstellte Dokumentation sehr nah am "echten" Code, sodass die Dokumentation relativ leicht aktuell zu halten ist. Mit jedem Commit und dem daraus resultierenden Build kann die Dokumentation immer wieder neu generiert und den Stakeholdern zur Verfügung gestellt werden.