Da ich zur Zeit eine gewisse Motivationsflaute habe, was das Debuggen des Toilet-Lisp-Compilers angeht, habe ich heute damit Zeit totgeschlagen, nach Dokumentationssystemen zu suchen, die ich verwenden könnte, um meinen Code ein bißchen zu illustrieren.

Nicht, daß ich nicht schon solche Systeme verwendet hätte. Den öffentlichen Teil von Objective-CL zum Beispiel habe ich recht gründlich dokumentiert, wofür ich mir selbst ein kleines Dokumentationsgenerationsskriptchen in Lisp geschrieben hatte. Leider ist dieses aber sehr stark auf Common Lisp zugeschnitten und könnte, so fürchte ich, nicht einmal ansatzweise für andere Sprachen herhalten (nun, vielleicht noch für Emacs-Lisp... ansatzweise).

Im Falle von Toilet Lisp gestaltet sich die Sache schwieriger. Zum einen besteht es aus viel mehr API, worauf mein Homebrew-Dokumentationssystem nun nicht gerade optimiert ist. Zum anderen ist Toilet Lisp in einer Kombination aus ganz verschiedenen Sprachen implementiert: Objective-C im Kern, Lisp in der Bibliothek und (seufz) Objective-C++ im Compiler. Sogar ein Perlskript war eine zeitlang dabei.

Ich könnte natürlich jeden Teil für sich dokumentieren, aber dann müßte ich mir verschiedene Dokumentierungskonventionen merken, und soviel Hirn habe ich nicht. Deshalb entschloß ich mich heute, ein wenig Zeit mit der Recherche über Dokumentationssysteme totzuschlagen, die mehrere Sprachen unterstützen.

Das Ergebnis ist, daß es so viele universelle Dokumentationssysteme gar nicht gibt, wie man annehmen könnte. Gefunden habe ich eigentlich nur zwei, die flexibel genug sind, um exotischere Sprachen wie Lisp und Objective-C zu unterstützen (ja, wirklich! Mit Objective-C sieht's da unerwartet düster aus): Robodoc und Natural Docs. Robodoc erzeugt leider optisch nicht so arg ansprechende Ergebnisse.

Apple bietet für Objective-C und einige andere Sprachen sein eigenes (ebenfalls freies) Tool namens HeaderDoc an. Ich habe es mir nicht genau genug angesehen, aber ich vermute, daß es auch einigermaßen gut möglich sein sollte, es für neue Sprachen anzupassen, da es bereits sehr verschiedenartige unterstützt.

Schließlich habe ich mich vorläufig für Natural Docs entschieden. Objective-C unterstützt es nicht von Haus aus, aber es war nicht schwer, ein kleines Perlmodul zusammenzuhacken, das ihm diese Fähigkeit verleiht.

Für den Fall, daß es jemand brauchen kann:

Download: Modul, Installationsanleitung.