Dokumentieren von Source Code mit Muse
2010-04-12
Emacs Muse eignet sich hervorragend zur Erstellung von technischer Dokumentation und auch zum Dokumentieren von Source Code, da es eine einfache Wiki-Syntax bietet und in viele unterschiedliche Formate publizieren kann (HTML, PDF, LaTeX, Info, DocBook und weitere).
Der folgende Demo-Artikel über Fibonacci-Folgen enthält ein kurzes JAVA-Programm und wurde von mir als Beispiel einmal in HTML und PDF) publiziert.
Unten steht der ursprünglichen Wiki-Text, aus welchem die jeweilige HTML und PDF Dokumentation generiert wurde. Später zeige ich dann, wie dieser Wiki-Text noch drastisch verkürzt werden kann, indem man beim Publizieren direkt den originalen Source Code verwendet, anstatt diesen zu kopieren.
Doch hier ist erst einmal der ungekürzte (und daher suboptimale) Wiki-Text:
#title Die Fibonacci-Folge
Bei der Fibonacci-Folge handelt es sich um eine unbegrenzte Folge von
Zahlen, bei der sich *die folgende Zahl durch Addition der beiden
vorhergehenden* ergibt. **Beispiel: 1, 1, 2, 3, 5, 8, 13, 21, 34, 55,...**
Da sich die Fibonacci-Folge selbst durch ein rekursives Bildungsgesetz
definiert, kann diese idealerweise anhand
[[http://de.wikipedia.org/wiki/Rekursive_Programmierung][rekursiver Programmierung]]
umgesetzt werden.
** Source Code
<src lang="jde">
// File: Fibonacci.java
public class Fibonacci {
static int fibonacci(int n) {
if ( (n==1) || (n==2) ) {
return 1;
} else {
return fibonacci(n-1)+fibonacci(n-2);
}
}
public static void main (String [] args) {
int max = (args.length>0 ? Integer.parseInt(args[0]) : 10);
for (int i = 1; i<=max; i++) {
System.out.println(fibonacci(i));
}
}
}
</src>
** Übersetzung, Aufruf & Ausgabe
<example>
$ javac Fibonacci.java
$ java Fibonacci
1
1
2
3
5
8
13
21
34
55
</example>
Und nun die optimierte Variante
Es ist ja sinnvoll die Dokumentation direkt neben dem Source-Code in einer Versionkontrolle nachzuhalten. Denn zum einen kann so konkurrierend an der Dokumentation gearbeitet werden und zum anderen können Änderungen zwischen Versionen einfacher nachvollzogen werden, bzw. stehen Code und Dokumentation immer als eine Einheit zur Verfügung, anstatt auf unterschiedlichen Medien verteilt zu sein.
Wir machen uns diese Tatsache, dass Source-Code und Dokumentation in einem gemeinsamen Projekt-Verzeichnis abgelegt sind, zu Nutze. Via dem
...
** Source Code
<command markup="src" lang="jde">
cat Fibonacci.java
</command>
...
Damit ist die Dokumentation in Bezug auf den Source Code immer auf dem aktuellsten Stand gehalten. So besteht keine Gefahr mehr, dass Beispiel-Code und tatsächlich ausführbarer Code auseinander driften, wenn z.B. Fehler korrigiert werden oder Schnittellen einer API verändert werden.
In dem darauf folgenden Schritt “Übersetzung, Ausführung und Ausgabe” werden nun sogar die Schritte zur Übersetzung, Ausführung und auch der Programm-Ausgabe mit den tatsächlich ausgeführten Kommandos selbst dokumentiert:
** Übersetzung, Aufruf & Ausgabe
<command markup="example">
set -x
javac Fibonacci.java
java Fibonacci
</command>
Zuerst wird das Shell-Kommando “set -x” ausgeführt. Dies führt zu einem Echo der jeweils nachfolgend ausgeführten Shell-Kommandos in der Standardausgabe. D.h. alle folgenden Shell-Kommandos werden mit ihrem eigenen Aufruf und ihrer Ausgabe selbst in den Wiki-Text mit einfließen.
Der folgende, komplette Wiki-Text generiert daher die gleiche Dokumentation, ist jedoch erheblich kürzer und ist durch die Nutzung des echten Source Codes immer auf dem aktuellsten Stand:
#title Die Fibonacci-Folge
Bei der Fibonacci-Folge handelt es sich um eine unbegrenzte Folge von
Zahlen, bei der sich *die folgende Zahl durch Addition der beiden
vorhergehenden* ergibt. **Beispiel: 1, 1, 2, 3, 5, 8, 13, 21, 34, 55,...**
Da sich die Fibonacci-Folge selbst durch ein rekursives Bildungsgesetz
definiert, kann diese idealerweise anhand
[[http://de.wikipedia.org/wiki/Rekursive_Programmierung][rekursiver Programmierung]]
umgesetzt werden.
** Source Code
<command markup="src" lang="jde">
cat Fibonacci.java
</command>
** Übersetzung, Aufruf & Ausgabe
<command markup="example">
set -x
javac Fibonacci.java
java Fibonacci
</command>
