BewertungBisher keine Bewertung
(Zum Abstimmen auf die Sterne klicken.)
Achtung: Der Download auf dieser Seite wird nicht mehr aktualisiert! Neue Updates sind ab sofort unter  https://github.com/DTJF/fbdoc verfügbar.
In vielen Programmiersprachen bzw. Entwicklungsumgebungen ist es üblich, die Dokumentation von Projekten direkt im Quelltext zu verfassen. Der Inhalt der Dokumentation wird in speziell markierte Kommentare platziert und von dort durch Hilfprogramme extrahiert, um die Dokumentation inklusive der Verlinkung von Symbolen, sowie der automatischen Formatierung und Indexierung zu erstellen.
Bedauerlicherweise existiert bisher kein vergleichbares Werkzeug für FB Quelltext. Deshalb wurde dieses Projekt gestartet. fb-doc unterstützt die automatische Erstellung von Dokumentation mit verfügbaren und paxisbewährten Standardtools, wie z. B. GTK-Doc (en) oder Doxygen.
Funktionsweise:
Dieses Archiv enthält den Quelltext zu dem Kommandozeilen-Tool fb-doc. Dieser wird zunächst kompiliert. Das Kompilat kann dann in verschiedener Art eingesetzt werden. Z. B. wird es im Quelltextordner eines FB Projektes gestartet und erzeugt den Ziel-Ordner ../doc/c_src (falls noch nicht vorhanden). Dann werden die FB Quelltexte geladen, geparsed und im Ziel-Ordner werden Dateien pseudo Quelltext in C Syntax erzeugt, welche die gleiche Struktur wie die FB Quelltexte haben (.bas wird zu .c, .bi wird zu .h) und auch die Dokumentationskommentare an gleicher Stelle enthalten. Der pseudo C Quelltext kann dann mit verfügbaren Tool-Chains für C Syntax bearbeitet werden, um die Dokumentation automatisch zu erstellen.
Die Dokumentation kann bei dieser Vorgehensweise wahlweise realen C Code enthalten. Z. B. wird
DECLARE FUNCTION abc (BYVAL xyz AS INTEGER) AS SHORT
zu
short abc (int xyz);
Oder es wird eine pseudo C Syntax generiert, die z. B. mit der Doxygen Tool-Chain zu einer FB ähnlichen Syntax verarbeitet werden kann. Das obige Beispiel wird dann zu
FUNCTION_AS_SHORT abc (BYVAL_AS_INTEGER xyz)
und kann in dieser Weise von FB Anwendern leicht interpretiert werden.
Beispiel:
Diese GooData-Dokumentation (Vorabversion) wird mit fb-doc und Gtk-Doc aus dem FB Quelltext erstellt. Beispielsweise wird die Beschreibung der Funktion goo_axis_new mit folgendem Quelltext erstellt:
'/**
'* goo_axis_new:
'* @Parent: the parent item, or %NULL. If a parent is specified, it will assume
'* ownership of the item, and the item will automatically be freed when it is
'* removed from the parent. Otherwise call g_object_unref() to free it.
'* @Back: the background box to connect the axis to (a #GooCanvasRect, #GooCanvasImage,
'* #GooCanvasGroup, ...). Note: to set the axis position and size, the properties
'* #GooCanvasItemSimple:x, #GooCanvasItemSimple:y, #GooCanvasItemSimple:width and
'* #GooCanvasItemSimple:height will be red (and therefore must be set in the
'* background box item).
'* @Text: the label text for the axis
'* @Modus: the position and type (like %GOO_AXIS_SOUTH or %GOO_GRIDAXIS_SOUTH, ...)
'* @...: optional pairs of property names and values, and a terminating %NULL.
'*
'* Creates a new axis item.
'*
'* Returns: (transfer full): a new axis item.
'**/
FUNCTION goo_axis_new CDECL( _
BYVAL Parent AS GooCanvasItem PTR, _
BYVAL Back AS GooCanvasItem PTR, _
BYVAL Text AS gchar PTR, _
BYVAL Modus AS GooAxisType, _
...) AS GooAxis PTR
' ...
Der FB Quelltext enthält Kommentare, wie sie für die Tools-Chain benötigt werden. Jeder Kommentar, der exportiert werden soll, beginnt mit einem "*". Dies gilt für Zeilenkommentare (beginnend mit ') und auch für /' ... '/ Kommentarblöcke. Für private Kommentare, die nicht in der Dokumentation erscheinen sollen, läßt man einfach den "*" weg.
Als weiteres Beispiel wurde mit fb-doc eine Grob-Dokumentation des FreeBasic Kompilers fbc-0.91.0 (858 MB) erstellt. Sie enthält die Namen der verwendeten Symbole (Makros, Variablen, Funktionen, ...) und mehr als 9800 grafische Darstellungen zu deren Vernetzung.
Und schließlich kann der Quelltext von fb-doc selbst als Beispiel dienen. Er enthält Kommentare für die Aufbereitung mit der Doxygen Tool-Chain (Link s. u.).
Seit Version 0.2 ist der Quelltext komplett überarbeitet und das Programm hat viele neue Funktionen erhalten:
- Komplettes Kommandozeilen-Tool mit help-Text und Versionsinfo
- Vollständige Übersetzung von Blöcken (jetz auch TYPE und / UNION)
- Schlüsselworte werden jetzt auch in gemischter Schreibweise erkannt (oder reine Kleinschreibung)
- Liest Input aus Dateien oder Pipe
- Schreibt Output in Dateien oder Pipe
- Verfolgt Quelltext-Baum (#INCLUDEs)
- Liest Dateien rekursiv in Unter-Ordnern
- Ausgabepfad kann spezifiziert werden
- Vollständiger Support für Doxygen (inkl. Filter-Funktion)
- Vorlagenerstellung zur beschleunigten Eingabe von Dokumentationskommentaren (Geany-Filter)
- Vier eingebaute Emitter (C-source, GtkDocTemplates, DoxygenTemplates, Callees)
- Interface für externe Emitter-Plugins zur Funktionserweiterung (mit Beispiel-Quelltext)
- Self-hosted Anleitung (en) mit Quelltext-Dokumentation (inkl. Diagrammen, s. u.)
Die Self-hosted Anleitung (en) kann hier online eingesehen werden oder ist als Baum von HTML-Dateien in diesem separaten Download verfügbar. Sie kann auch aus dem Quelltext erstellt werden, nachdem fb-doc kompiliert und installiert wurde, sowie die Doxygen Tool-Chain und Graphviz installiert wurden.
Die weiteren Screenshots zeigen Beispiel-Diagramme aus der Dokumentation, die automatisch mit Doxygen und Graphviz aus dem Quelltext erzeugt wurden. In der Anleitung sind diese Diagramme mit dem Text verlinkt. Durch diese und weitere Verlinkungen wird die Navigation in den Seiten wesentlich unterstützt.
EnglishSee english forum thread
|
Wer ist online?
Buchempfehlung
FreeBASIC-Chat
FreeBASIC-Nachrichten jetzt auch über Twitter erhalten. Follow us!
FreeBASIC 0.23.0
Quelltext enthalten
