Madoc ist ein Modul für Microsoft Access für die Erzeugung von Code Dokumentationen analog zu den JavaDoc Dokumentationen. Es werden dabei ähnliche Tags verwendet wie in Java und auch die HTML Ausgabe ist ähnlich aufgebaut.

Features

• Erzeugung von Code Dokumentation
• Auflistung der Module (analog zu den Klassen in Java)
• Auflistung der Funktionen zu Prozeduren zu Modulen
• Gesamtauflistung sämtlicher Funktionen und Prozeduren in allen Modulen
• Detailansicht von Funktionen und Prozeduren
• Grafische Hervorhebung von privaten und öffentlichen Funktionen und Prozeduren
• Grafische Unterscheidung zw. Funktionen und Prozeduren
• Unterstützung von Moduldokumentation
• Unterstützung von verschiedenen HTML Tags in allen Dokumentationen
• Hyperlink Verweise auf andere Module/Funktionen/Prozeduren (eingeleitet mittels @see-Tag)
• Einfache Anpassung, da einfaches Stylesheet
• Optional Erzeugung von Inhaltsverzeichnissen im Modul-Code

Verwendung

Grundsätzlich wird der erste Dokumentationsblock vor der ersten Anweisung im Modul als Moduldokumentation interpretiert. Bei Funktionen und Prozeduren wird der Dokumentationsblock unmittelbar vor der Signatur interpretiert.

Sämtlicher Text kann mittels den HTML Tags <b>…</b> als fett, mittels <i>…</i> als kursiv, mittels <u>…</u> als unterstrichen und mittels <code>…</ code> als monospaced formatiert werden.

Um einen neuen Paragraph zu erzeugen, kann eine leere Zeile verwendet werden. Ansonsten werden Zeilen automatisch konkateniert. Um innerhalb eines Paragraphs eine neue Zeile zu erzwingen kann im Text das HTML Tag <br /> eingefügt werden.

Zudem können mit den Tags <h1>, <h2>, <h3> und < h4> (und den entsprechenden schliessenden Tags) unterschiedliche Überschriften eingefüht werden. Diese Überschriften sollten jedoch nur in der Modulbschreibung verwendet werden.

Moduldokumentation

Die Moduldokumentation besteht ausschliesslich aus einer Beschreibung.

Funktions-/Prozedurdokumentation

Die erzeugte Dokumentation wird automatisch aus der Signatur abgeleitet. Zusätzlich kann eine Kurzbeschreibung, eine ausführliche Beschreibung und eine Paramter- bzw. Rückgabewert Dokumentation verfasst werden.
Dabei beinhaltet die erste Zeile in jedem Fall die Kurzbeschreibung. Sämtliche nachfolgenden Zeilen werden als ausführlich Beschreibung interpretiert, bis entweder eine Separatorzeile (z.B. '***... oder '---) oder ein Tag (z.B. @param) gefunden wird.

Parameterbeschreibung

Paramter werden mit dem Schlüsselwort @param, dem Paramternamen und der anschliessenden Dokumentation erfasst. Dabei kann auch hier die Dokumentation mehrzeilig sein. Sie endet ebenfalls bei einer Trennzeile oder bei einem anderen Tag.
Bsp.: ' @param strText Irgendeintext

Rückgabewertbeschreibung

Der Rückgabewerte kann mit dem Schlüsselwort @return dokumentiert werden.
Bsp.: ' @return Irgendetwas

Verwendung

Mit dem Tag @use kann die Verwendung der Funktion/Prozedur weiter spezifiziert werden.
Bsp.: ' @use So muss es verwendet werden

Veraltete Funktionen/Prozeduren

Mit dem Schlüsselwort @deprecated kann eine Funktion oder Prozedur als veraltet gekennzeichnet werden. Hier dem Schlüsselwort kann ein zusätzlicher Hinweis notiert werden (z.B. die Ersatzfunktion) Bsp.: ' @deprecated Neu die Funktion neueFunktion() verwenden

Referenzen

Um auf eine andere Dokumentation zu referenzieren kann das Schlüsselwort @see verwendet werden. Dahinter kann ein Freitext erfolgen. Es kann aber auch auf eine anderen Funktion/Prozedur referenziert werden, indem diese vollständig mit Modulnamen qualifiziert wird. In diesem Fall wird die Angabe automatisch in einen Link in der Dokumentation umgewandelt.
Bsp.: ' @see Modul1.meineFunktion

Weitere Angaben

Mit dem Paramter @author kann der Autor der Funktion/Prozedur niedergeschrieben werden. Diese Angabe wird in der Dokumentation jedoch nicht wiedergegeben

Dokumentations-Erzeugung

Für die Erzeugung einer Dokumentation muss das Modul madoc importiert werden. Dieses Modul besitzt eine Funktion madocStart( ), welche die Dokumentation und allfällige Inhaltsverzeichnisse für sämtliche Module erzeugt.

History

1.0.0

• Initialversion