Homepage: http://delphidoc.sourceforge.net/
Project-Page: http://sourceforge.net/projects/delphidoc/

JADD - Just Another DelphiDoc

Um DelphiDoc herunterzuladen bitte auf der Projektseite auf die veröffentlichten Dateien gehen.

Die deutsche Dokumentation wird nicht mehr aktiv gewartet.
Der Aufwand ist einfach zu groß geworden nach dem Aufsplitten der Hilfe in mehrere Dateien.
Die hier erklärten Grundlagen dürften noch für die nächste Zeit Gültigkeit haben, die neusten Features werden aber nicht mehr hinzugefügt.
Vielleicht habe ich zu einem späteren Zeitpunkt wieder mehr Zeit und eine neue Organisation und kann so zumindest diese allgemeine Dokumentation wieder aufnehmen.

Um die Dokumentation auf Deutsch zu erzeugen, kann man im Hauptfenster im Tab "Localization" hinter "Use predefined Language" einfach "Deutsch" (oder "german" oder "de") auswählen.

• Was ist das?
• Verwendung
• Kommentare
• Rechtliches
• Kontakt

Was ist das?

DelphiDoc ist ein Programm zur automatischen Erstellung von Dokumentation über ein Delphi-Projekt. Dies geschieht momentan im HTML-, im Windows-Hilfe-Format (.hlp-Dateien), im L^AT_EX-Format und im PDF-Format. Die neue HTML-Hilfe (.chm) ist ebenfalls verfügbar und ein Export zu XMI zum import in UML-Modelling-Tools ebenfalls. Außerdem können Diagramme erstellt werden.

Ich habe DelphiDoc geschrieben, um mein Vordiplomsprogramm zu dokumentieren, da es den Umfang einer vollkommenden Dokumentation per Hand doch etwas sprengte. Vorausgesetzt man will das ganze auch synchron halten und auch die Zeit zum Programmieren und nicht zum Dokumentieren nutzen.

Seine bedeutendsten Eigenschaften (auch in Bezug auf andere Programme, die ebenfalls zum Kommentieren von Delphi-Programmen gedacht sind) sind ein extensives Parsen des Quelltextes und eine Aufspaltung in Parser und Dokumentationsgenerator. Aus dem Erstem folgt, daß sehr viele Informationen gesammelt werden, die in die Dokumentation einfließen können, was diese wertvoll machen kann, selbst wenn es keine Kommentare gibt (sehr praktisch zum Einarbeiten in fremde Projekte, wenn man die erzeugte Windows-Hilfe in die von Delphi integriert).
Das Zweite führt zu austauschbaren Dokumentationsgeneratoren. Momentan kann zwischen verschiedenen Generatoren gewählt werden um die Dokumentation in den oben erwähnten Formaten zu erzeugen.

Verwendung

Dieser Abschnitt ist recht einfach gehalten mit nur den grundlegendsten Funktionen. Für eine komplette und aktuellere Beschreibung muß ich hier leider auf die englische Dokumentation verweisen.

Um die Dokumentation zu erstellen, muß man als erstes das Projekt hinzufügen. Dies geht am einfachsten, in dem man die .dpr-Datei aus dem Explorer in das obere der Listenfenster zieht, und danach den Hacken neben den entstandenen Eintrag setzt. Danach muß man auf den Schalter Parse klicken, um die die Quellen zu parsen, und anschließend den Schalter Generate Documentation auf der vierten Lasche um die Dokumentation in das darunter angegebene Verzeichnis (dies wird automatisch angelegt, wenn noch nicht vorhanden) mit dem rechts angegebenen Hilfe-Generator zu generieren.

Der Schalter Compiler Options ist zum Einstellen der Compiler-Einstellungen gedacht, diese sind für die meisten Projekte nicht relevant. Die Einstellungen werden bei Projekten aus den zugehörigen .cfg-Dateien extrahiert, so das dieses Formular wirklich nur selten benötigt werden sollte. Die korrekte Delphi-Version muß aber u.U. mit dem nebenstehenden Eingabefeld ausgewählt werden.

Der Schalter Parse liest alle angegeben Dateien ein und parst sie untereinander. Nach dem Erstellen der interner Datenstrukturen über die Dateien kann dann weitergearbeitet werden, um z.B. die Dokumentation zu erstellen. Etwaige bereits geparste Daten werden verworfen, bevor erneut geparst wird. Der Schalter Manually bietet die Möglichkeit die zu parsenden Dateien nacheinander auszuwählen und jederzeit einzelne Dateien vom Parsen wieder auszuschließen. Projekte und ganze Verzeichnisse werden korrekt eingelesen und erkannt. Erst wenn die Auswahl beendet ist, werden alle Dateien zusammen komplett geparst.

Der Schalter Generate Documentation erzeugt die Dokumentation in dem unter Generator ausgewähltem Format des vorher geparsten Quellcodes in das in dem darunterliegendem Editierfeld angegebenen Verzeichnis. Im Editierfeld Name of Project kann der Name des Projektes angegeben werden, der in die generierte Dokumentation mit eingefügt wird.

Mit dem Schalter By Category zeigt alle Optionen des gewählten Generators an eingeordnet nach ihrer Kategorie. As List zeigt sie ähnlich dem Objektinspektor von Delphi als eine Liste zum Bearbeiten ab. Einige der eingestellten Werte können verloren gehen, wenn ein anderer Generator ausgewählt wird, der nicht die entsprechenden Optionen besitzt.

Falls die Dokumentation im Format HTML erfolgt, werden eine Menge von HMTL-Dateien im angegebenen Verzeichnis erzeugt, die Hauptdatei heißt index.html. Außerdem werden ein paar Xfig-Dateien (*.fig) und WMF-Dateien (*.wmf) angelegt. Diese zeigen die Verhältnisse von Dateien und Klassen/Schnittstellen untereinander an. XFig-Dateien enthalten Grafiken im Vektor-Format, sind aber im Gegensatz zu WMF-Dateien als Text gespeichert. Es stammt aus der Unix-Welt, es gibt aber Programme zum Betrachten und Bearbeiten der Dateien unter Windows. WMF-Dateien sollten z.B. normalerweise in den meisten Office-Programmen einfügbar sein.

Falls die Dokumentation im Format WinHelp erzeugt wird, wird ein Hilfe-Projekt samt einer RTF-Datei erzeugt, die sich zu einer Windows-Hilfe-Datei kompilieren läßt. Dazu wird der Hilfe-Compiler von Microsoft benötigt. Dieser kann kostenlos heruntergeladen werden bei Microsoft, er ist aber auch auf der Delphi-CD (oder anderen SDKs) enthalten, und wird unter Umständen sogar installiert in das Verzeichnis C:\Programme\Borland\Delphi4\Help\Tools. Ist dieser installiert und wurde einmal gestartet, ist die erstellte Datei DelphiDoc.hpj verknüpft und kann damit direkt geöffnet werden.
Das Compilieren zu einer Hilfe-Datei kann dann durch Save and Compile oder nur durch Befehle zum Compilieren gestartet und so die Datei DelphiDoc.hlp erzeugt werden. Über die Expert-Optionen kann dies auch automatisch erfolgen, u.U. muß dazu der Pfad zum Hilfe-Compiler angegeben werden, es wird aber versucht ihn auch ohne diese Angabe zu finden. Dazu wird geprüft, ob er mit Delphi installiert wurde, ob die Datei des Hilfeprojektes verknüpft ist oder ob der Compiler im Suchpfad zu finden ist.
Die entstandene Hilfe-Datei kann auch in die Hilfe von Delphi integriert werden. Dazu muß das Programm OpenHelp C:\Programme\Borland\Delphi4\Bin\oh.exe aufgerufen werden, dann das Projekt C:\Programme\Borland\Delphi4\Help\delphi4.ohp geöffnet werden und nach dem Auswählen vom Tab Index die erzeugte Hilfedatei einfach hinzugefügt werden. Nach dem Speichern sollte in Delphi Hilfe zu den Bezeichnern des Projektes einfach per F1 abrufbar sein, genauso, wie auch normalerweise zu den Bezeichnern von Delphi.
Achtung: Bevor die Hilfedatei in Delphi integriert wird, sollte sie umbenannt werden, da sonst das automatische Anzeigen der Hilfe nach dem Erstellen in DelphiDoc nicht richtig funktioniert und die integrierte Hilfedatei statt der frisch generierten angezeigt wird (per Hand läßt sich die generierte Hilfedatei immer noch anzeigen). Scheinbar werden die Hilfedateien über den Dateinamen gecached oder über einen Suchpfad gesucht, weshalb mit gleichnamigen Dateien Probleme auftreten.

Falls die Dokumentation im Format L^AT_EX erfolgt, werden mehrere .tex-Dateien erzeugt. T_EX ist ein Textsatzsystem, das benutzt werden kann, um die Dokumentation in vielen verschiedenen Formaten zu erzeugen. Dies beinhaltet PostScript um es direkt zu drucken und PDF (Portable Document Format von Adobe) das auf vielen Plattformen portabel angesehen werden kann mit Adobes Acrobat Reader.
Um die Dokumentation in diesen Formaten zu generieren wird natürlich das L^AT_EX-System benötigt. Es kann kostenlos aus dem WorldWideWeb geladen werden, dafür sollte man ein Blick auf folgende Seiten werfen: die Deutschsprachige Anwendervereinigung TeX e.V., the Latex-Project, the (a) TeX Users Group und the the Comprehensive TeX Archive Network.
Einfach latex mit der erzeugten Hauptdatei DelphiDoc.tex starten. In ihr sind verschiedene Macros/Befehle definiert, die man ändern kann oder u.U. auch muß.

Im Format PDF (Portable Document Format (Portierfähiges Dokumentformat), von Adobe) wird nur eine einzige PDF-Datei erstellt. Diese kann beispielsweise mit Adobes kostenlosen Acrobat Reader angezeigt oder gedruckt werden.

Mit Load und Save kann man die Einstellungen der zu dokumentierenden Projekte in Dateien speichern/aus sie lesen. Diese Dateien können auch direkt beim Programmstart als Parameter angegeben werden.

In den drein darunterliegenden TCheckListBoxen wird eingestellt, was geparst werden soll und was nicht. Die obere gibt alle Dateien und Verzeichnisse an, die/deren Inhalt geparst werden soll. Die mittlere gibt ensprechend alle Dateien/Verzeichnisse an, die nicht geparst werden sollen, auch wenn sie in der oberen indirekt enthalten sind. In der untersten können zusätzlich Bibliothekspfade/Suchpfade eingegeben werden; Dateien in diesen werden nur geparst, wenn sie von anderen geparsten verwendet werden.

Hat man also folgende Verzeichnisstruktur:
\a
\a\b1
\a\b1\c1
\a\b1\c2
\a\b2
und gibt in der oberen Liste \a und \a\b1\c2 an, und in der unteren Liste \a\b1, alle Einträge jeweils mit Haken, werden alle Pascal-Dateien in a, c2 und b2 geparst.

Mit dem Editfeld und den sechs Schaltern bearbeitet man diese drei Listen. Mit dem jeweils oberen Schalter wird der in dem Editfeld angegebene Pfad zu der entsprechenden Liste hinzugefügt, mit dem unteren entsprechend der in der Liste gewählte Eintrag wieder gelöscht.

Die Haken neben den Enträgen bedeuten rekursiv:
In der oberen Liste bedeutet ein Haken neben einem Verzeichnis, daß auch alle Dateien in enthaltenen Verzeichnissen geparst werden sollen. Ist es eine Datei bedeutet er, daß, sofern es sich um eine Projekt-Datei handelt, auch alle benutzten Dateien, also die im Projekt enthaltenen Dateien, ebenfalls geparst werden sollen.
In der unteren Liste gilt es bei Verzeichnissen entsprechend: Ist bei ihnen kein Haken gesetzt, werden nur die Dateien direkt in dem Verzeichnis ignoriert, sonst auch in untergeordneten Verzeichnissen. Bei Dateien hat der Haken keine Auswirkungen.

Die Datei PreDefinedIdents.txt enthält eine Liste von vordefinierten Bezeichnern, sie ist bei weitem nicht vollständig. Alle beim Parsen gefundenen unbekannten Bezeichner, die nicht in dieser Datei stehen, werden aufgelistet.
Die Datei SystemIdents.txt enthält die Liste der im Compiler vordefinierten Bezeichner, die in der Unit System angenommen werden, und die Datei SystemTypes.txt entsprechende Typen. Diese werden definiert, wenn man die Unit System parst, ansonsten sind die Dateien belanglos.

Kommentare

Kommentare werden oberhalb von Bezeichnern erwartet und auf der gleichen Zeile. Dies ist die Hauptvoraussetzung für Kommentare. Kommentare müssen nicht besonders markiert werden (z.B. durch ein oder mehrere Sternchen "*") um verwendet zu werden. Falls beispielsweise eine Prozedur kommentiert wird, werden verschiedene Abschnitte erwartet, um z.B. die Parameter zu beschreiben. Werden diese nicht gefunden, wird zwar eine Warnung im Log erzeugt, die Dokumentation erfolgt aber trotzdem. Daher kann auch für nicht speziell für DelphiDoc kommentierte Projekte Dokumentation erzeugt werden. Die (korrekten) Kommentare werden aber nur verwendet, wenn sich diese an den oben genannten Stellen befinden. Aber selbst ohne sie kann Dokumentation erzeugt werden; durch die Verlinkung kann immer noch eine brauchbare Übersicht der Beziehungen der Bezeichner untereinander erzeugt werden.

Kommentare werden geparst, dazu werden sie als erstes in einzelne Abschnitte eingeteilt. Das Zeichen "~" (die Tilde) stellt dabei das Sonderzeichen dar. Abschnitte werden durch ~Abschnittsname eingeleitet, momentan gibt es neben dem Standardabschnitt am Anfang des Kommentars die Abschnitte:
deprecated, todo, feature, see, seeText, param, result, exception, example, author, version und page.
Für das Sonderzeichen kann anstatt der Tilde auch ein anderes eingestellt werden, ebenso können in den Optionen des Generators die Namen der Abschnitte geändert werden und es stehen drei weitere frei definierbare zur Verfügung.

Syntax:

     Text

Der Standardabschnitt enthält die normale Dokumentation, bei einigen Bezeichnern (bisher nur in HTML bei Funktionen) wird der erste Satz als Kurzzusammenfassung verwendet.

~deprecated [Text]

Markiert den Bezeichner/die Datei als veraltet, also, daß sie nicht mehr genutzt werden sollte und demnächst gelöscht wird. Der u.U. folgende Text wird in die Dokumentation einkopiert.

~todo Text

Der Text wird entsprechend aufgelistet und eine Eintrag in der Liste mit noch allen zu erledigenden Sachen erzeugt.

~feature Text

Der Text wird entsprechend aufgelistet und eine Eintrag in der Liste mit noch allen zu erweiterten Sachen erzeugt.

~see Identifier [Text]

Es wird ein Link auf den nachfolgend angegebenen Bezeichner generiert. Ein möglicherweise (kurzer) nachfolgender Text (z.B. mit einer Begründung) wird ebenfalls eingefügt. Dieser Abschnitt kann mehrmals verwendet werden.

~seeText Text

Der Text wird ebenfalls einkopiert, er kann durchaus länger sein, ist aber auch nur für kürzere Verweise auf externe Sachen gedacht, wie z.B. die Delphi-Hilfe. Dieser Abschnitt kann ebenfalls mehrmals verwendet werden.

~param ParamName[, ParamName]* Text

Der Text wird als Dokumentation der angegebenen Parameter verwendet. Der Text wird für jeden Parameter einzelnd ausgewertet, so daß z.B. ein ~[inheritDoc] (s.u.) jeweils einen anderen und damit korrekten Text zurückliefert. Normalerweise sollte für jeden Parameter der Funktion ein eigener Abschnitt existieren.

~result Text

Die Dokumentation des Rückgabewerts einer Funktion.

~exception ExceptionType Text

Der Type einer in der Funktion möglicherweise ausgelösten Exception nebst der Erklärung, wann dies geschehen kann wird durch diesen Abschnitt angegeben. Dieser Abschnitt kann mehrmals verwendet werden.

~example Text

Ein Beispiel zu dem Bezeichner wird angegeben. Der Text wird als normaler Text interpretiert, will man also Code einbetten muß dieser entprechend formatiert sein (s.u.). Dieser Abschnitt kann mehrmals verwendet werden.

~author

Legt einen eintrag (ode reine Liste) mit dem folgenden Text an.

~version

Legt einen eintrag (ode reine Liste) mit dem folgenden Text an.

~page PageName [Title of Page] Text

Dieser Abschnitt ist nur gültig in per ~[userDoc FilePath] eingefügte Dateien zur Dokumentation des Projektes losgelöst von einem bestimmten Bezeichner. Genauer gesagt, sollte sich die Dokumentation in den Datei in solchen Abschnitten befinden. Jeder Abschnitt stellt ein eigene Seite da. Der erste Parameter stellt den Namen der Seite da, zu der mit ~[linkPage PageName] ein Link erzeugt werden kann. Die Rest der Zeile stellt den Titel der Seite dar, ist die erste Zeile leer, wird (nur) die zweite versucht. Ist diese auch leer, hat die Seite keinen Titel. Der Name "Index" ist reserviert für den Index der Dokumentation.

~gui*

Für das Erstellen von Dokumentation als Hilfe für eine GUI bitte die entsprechende englische Dokumentation ansehen.

Je nach Logik des zu kommentierenden Bezeichners werden diese Abschnitte ausgewertet und in die Dokumentation des Bezeichners eingefügt. Dabei wird "~~" als einfache Tilde behandelt (die Tilde wird also mit sich selbst gequoted). "~[[" wird durch "[" und "~[]" durch "]" ersetzt. "~[" drückt einen Befehl aus. Mit
~[Befehl Param1 Param2 Und ein beliebiger Text auch mit anderen Befehlen]
kann die entsprechende Klammer durch einen anderen Text ersetzt werden.

~[ Text]

Der Text wird enstprechend übernommen.

~[link Identifier [Text]]

Es wird ein Link auf den Bezeichner eingefügt. Wenn kein Text angegeben wurde, wird der Text für Identifier als Link-Text verwendet.

~[link .Member [Text]]

Das gleiche für Felder der aktuellen Klassen/Record/etc.

~[link Identifier.Member [Text]]

Ein weiteres Beispiel

~[link Unit.Identifier [Text]]

Ein weiteres Beispiel

~[link Unit.Identifier.Member [Text]]

Ein weiteres Beispiel

~[linkClass ClassIdentifier [Text]]

Es wird zwingend eine Klasse mit dem Namen gesucht.

~[linkUnit UnitName [Text]]

Es wird zwingend eine Datei mit dem Namen gesucht.

~[linkExtern URI [Text]]

Erzeugen eines Links zu der angegebenen externen (außerhalb der erzeugten Dokumentation liegenden) URI.

~[defineText Doc_Text_Name Text]

Speichert Text unter dem Namen Doc_Text_Name intern ab.

~[defineTextIf Text1 [_]Operator Text2 Doc_Text_Name Text]

Speichert Text unter dem Namen Doc_Text_Name intern ab, falls Text1 zu Text2 die durch den Operator ausgedrückte Beziehung hat. Fängt dieser mit einem Unterstrich "_" an, werden beide Texte vor dem Vergleich in Kleinschreibung umgewandelt.

~[insertText Doc_Text_Name]

Fügt den gespeicherten Text ein.

~[insertVariable Doc_Variable_Name]

Fügt den variablen Text des Namens ein. Der Text wird vom Generator bereitgestellt, es hanfdelt sich nicht um Benutzer-Variablen wie in ~[insertText Doc_Text_Name]. Der Text kann sich ändern, abhängig vom Ort und Zeitpunkt wo er abgefragt wird. Für eine Aufzählung der Namen siehe unten.

~[includeFile FilePath [Fail-Text]]

Fügt den Inhalt der angegebenen Datei ein, war dies nicht möglich, wird der nachfolgend angegebene Text normal eingefügt. Der Text wird direkt eingefügt, sollte sich also mit dem Format des Generators kompatibel sein und auch an die Stelle hineinpassen.

~[inheritDoc]

Erbt die Dokumentation des Abschnitts vom Vorfahren sofern möglich. Nur möglich bei class/object/interface mit einem dokumentierten Vorfahren oder eine überschriebene Methode einer solchen oder bei Neudeklarationen von Eigenschaften. Außerdem ist es auch nur im Standardabschnitt am Anfang und im ~param und ~result-Abschnitt möglich.

~[em Text]

Gebt den Text hervor, dies geschieht meist durch Kursivstellen des Textes.

~[code Text]

Fügt den Text als (kurzen) Code-Abschnitt ein.

~[preformatted Text]

Fügt den Text als vorformatierten Text ein (Zeilenumbrüche und Einrückungen bleiben erhalten).

~[sample Text]

Fügt den Text als (längeres) Code-Beispiel ein, ähnlich ~[preformatted ~[code Text]].

~[br]

Erzeugt einen Zeilenwechsel.

~[p]

Fügt einen Absatz ein.

~[add Integer Integer]

Addiert die beiden ganzzahligen Werte und gibt das Ergebnis zurück. Ist einer der beiden Werte ein leerer Text, wird der andere direkt zurückgegeben. Sind es keine gültigen Zahlen wird ein leerer Text zurückgegeben.

~[userDoc FilePath [Fail-Text]]

Liest die angegebene Datei zur allgemeinen Dokumentation des Projektes losgelöst von Bezeichnern. Kann sie nicht gelesen werden wird der nachfolgende Text zurückgegeben sonst keiner. Der Inhalt der Datei wird genauso wie ein Kommentar gehandhabt, es gilt also die gleiche Syntax. Genauer gesagt, muß sich die Dokumentation in ~page-Abschnitte aufteilen, die die einzelnen Seiten der Dokumentation darstellen, der Text vor dem ersten Abschnitt wird in den Index eingefügt, sollte daher möglichst kurz (oder nicht-existent) sein, kann aber z.B. genutzt werden um weitere Dokumentationsdateien einzulesen. Wurde sie bereits eingelesen wird dieser Befehl ignoriert.

~[linkPage PageNameOrNumber Text]

Fügt einen Link zu der angegebenen Seite ein. Es kann sowohl der Name der Seite als auch die Seitennummer (beginnend mit Null) angegeben werden. Wird "Index" angegeben wird ein Link zum Index der Dokumentation erzeugt. Der nachfolgend angegebene Text wird als Text des Linkes benutzt. Ein paar Beispiele:

~[linkPage Index Index of the Documentation]
~[linkPage 0 Link to first Page]
~[linkPage FirstPage Link to a Page called "FirstPage"]
~[linkPage ~[insertVariable ThisPageName] Link to this Page]
~[linkPage ~[insertVariable ThisPage] Link to this Page]
~[linkPage ~[add ~[insertVariable ThisPage] 1] Link to next the Page]
~[linkPage ~[add ~[insertVariable ThisPage] -1] Link to the previous Page]

~[HelpContext number]

Setzt die Nummer des Hilfekontexts des momentanen Kommentars. Diese wird ignoriert, wenn keine Windows Hilfedatei oder Windows HTML Hilfe generiert wird.

~[linkGUI TopicName Text]

Fügt einen Link zu der angegebenen Dokumentation einer Komponente von der zu dokumentierenden GUI ein.

~[image [Alignment=char] [ConvFormat/Ext=JPEG|JPG] [Resolution=WxH|0x0] Drive\Path\ImageFile[.ext] [Alternative Text] ~[imageLink ...]* ]

Fügt ein Bild in die Dokumentation ein, für eine genauere Beschreibung bitte die englische Version durchlesen.

~[imageLink "all"|Left,Top,Right,Bottom Link-InlineCommand LinkTarget [Alternative Text]]

Erzeugt einen Link innerhalb des momentan einzufügende Bild, für eine genauere Beschreibung bitte die englische Version durchlesen.

~[diagram Parameter*]

Erzeugt ein Diagram aus dem geparsten Quellcode und für es in die Dokumentation ein, für eine genauere Beschreibung bitte die englische Version durchlesen.

DocClass

Liefert den Namen der Klasse, die die Dokumentation erstellt zurück, momentan "THTMLDoc", "THTMLHelpDoc", "TWinHelpDoc", "TLaTeXDoc" oder "TPDFDoc".

DefinitionColumn

Fügt die Spalte ein, in die der momentane Bezeichner definiert wurde.

DefinitionLine

Fügt die Zeile ein, in die der momentane Bezeichner definiert wurde.

FileName

Liefert den internen Namen der aktuellen Datei zurück. ~[link ~[insertVariable FileName] In dieser Datei] erzeugt also (meistens) einen Link auf die Datei selber.

FileSize

Fügt die größe der momentanen Datei ein, diese kann von der korrekten Größe leicht abweichen, abhängig vom verwendeten Zeilenenden-Modus (CRLF, LF).

FileType

Liefert den Type der aktuellen Datei zurück, also unit, program, library oder package.

ForwardDefinitionColumn

Fügt die Spalte ein, in die der momentane Bezeichner erstmals definiert wurde.

ForwardDefinitionLine

Fügt die Zeile ein, in die der momentane Bezeichner erstmals definiert wurde.

NumberOfLines

Fügt die Anzahl der Zeilen der momentanen Datei ein.

ThisPageName

Liefert den Name der aktuellen Seite zurück, beispielsweise um einen Link auf sie zu erzeugen.

ThisPage

Liefert die Nummer der aktuellen Seite zurück, beispielsweise um einen Link auf sie oder einer Seite relativ zu ihr (durch hinzuzählen/abziehen einer Zahl mit ~[add ]) zu erzeugen.

Rechtliches

Nun ja, hier ist nichts besonderes. Das Programm wird wie-es-ist bereitgestellt, das heißt, es macht was es macht, und das ist hauptsächlich das Einlesen von Pascal Code und das Generieren von Dokumentation. Benutzung auf eigene Gefahr, auch wenn ich mir keinen Schaden vorstellen kann, den es anrichten könnte, außer dem Überschreiben von Dateien in dem Verzeichnis in dem die Dokumentation generiert werden soll. DelphiDoc wird nun unter der GPL veröffentlicht, entsprechend muß man sie anerkennen um das Programm nutzen zu können. Eine (rechtlich nicht anwendbare) Übersetzung auf Deutsch kann vielleicht hilfreich sein für das Verständnis.

Und noch eine Bemerkung zur generierten Dokumentation:
Die generierte Dokumentation erbt ihren rechtlichen Status von der Quelle (dem Quellcode) von der sie generiert wurde, d.h. wenn man die Software geschrieben hat und DelphiDoc generiert Dokumentation darüber, hat man (der Autor der Software) auch das Urheberrecht an der Dokumentation.

Kontakt

Zu Fragen und Anregungen usw. kann man mich in nächster Zeit noch unter meiner FH-Email-Adresse erreichen, also unter wi5337 @ fh-wedel.de (bitte Adresse per Hand zusammensetzen, ich möchte die Adresse nicht den automatischen Suchmaschinen für Spam auf dem Silbertablett servieren). Ich habe nun auch DelphiDoc @ gmx.de registriert, so daß ich auch darüber verfügbar bin. Es wäre aber wahrscheinlich besser direkt die verschiedenen SourceForge-Dienste zu nutzen.

DelphiDoc sollte die meisten korrekten und compilierfähigen Programme korrekt parsen können, es gibt aber einige Konstrukte, die Probleme verursachen könnten (es ist schon krank, was man alles in Delphi hinschreiben kann, was dann korrekt compiliert wird). Es wird in den meisten Fällen die Datei mit Zeilen- und Spaltennummer ausgegeben, wenn ein Fehler beim Parsen auftreten sollte. Die meisten dieser Konstrukte sollten allerdings kaum genutzt werden (nein, ich meine nicht goto damit, das sollte korrekt geparst werden können).

Sollte ein Fehler auftreten, obwohl der zu parsende Quellcode korrekt ist, bitte ich darum, DelphiDoc erneut zu starten, und es noch einmal zu versuchen, um Folgefehler zu vermeiden, auch wenn die bei der aktuellen Version nicht mehr vorkommen sollte. Sollte der Fehler trotzdem auftreten, kann man mir mit der Fehlerbeschreibung und einem relevanten Auszug des Codes, oder bei komplizierteren Konstrukten auch des gesamten Projektes, eine entsprechende E-Mail zukommen lassen.

MfG Gerold Veith