PasDoc - Teil 1: Grundlagen

Antworten
monta
Lazarusforum e. V.
Beiträge: 2809
Registriert: Sa 9. Sep 2006, 18:05
OS, Lazarus, FPC: Linux (L trunk FPC trunk)
CPU-Target: 64Bit
Wohnort: Dresden
Kontaktdaten:

PasDoc - Teil 1: Grundlagen

Beitrag von monta »

Kategorie: Werkzeuge
Typ: Tutorial

Artikel Name: PasDoc - Teil 1: Grundlagen
Autor: monta
Beschreibung: Grundlagen zu PasDoc und zur Kommentarsyntax


Der Einsatz von pasDoc zur Pascal-Sourcecode-Dokumentation

Spätestens wenn man seinen Quellcode weitergibt, bzw. veröffentlicht, wird man in den meisten Fällen nicht daran vorbei kommen, eine entsprechende Dokumentation (zumindest der wichtigsten Dinge) zu erstellen.
Welchen Weg man dabei wählt, ist von individuellen Geschmack abhängig.

Im folgenden soll ein kurzer Einblick in die Benutzung von PasDoc zur automatischen Generation von Sourcedokumentationen gegeben werden. Dabei ist grundlegend zu beachten, das PasDoc die Struktur zwar aus den einzelnen Units extrahiert, Beschreibungen dazu jedoch in Form von Kommentaren bereits im Quelltext vorhanden sein müssen, damit mit minimalem
Aufwand die Dokumentation automatisch generiert werden kann.

Grundlagen:

Pasdoc besitzt seinen eigenen Parser, mit welchem es die Unitdateien durchläuft. Somit ist es (im Unterschied beispielsweise zu (FPDoc) vom installierten System unabhängig und kann somit praktisch auf jede Pascalunit angewandt werden, egal von welchem System sie stammt und ob beispielsweise Freepascal installiert ist.

Die Tatsache, dass zusätzliche Informationen aus Kommentaren extrahiert werden, schreibt eine festgelegte Syntax dieser vor.

PasDoc Syntax

Die gefundenen Kommentare werden dabei einem entsprechenden Eintrag (Item) zugeordnet, wobei es sich um eine Unit, Klasse, Funktion, Prozedur, Variable, Konstante oder ein Objekt handeln kann.

Standardmäßig werden Kommentare dem darauf folgenden Item zugeordnet:

Code: Alles auswählen

{ Beschreibung von Unit1 }
unit Unit1;
 
interface
 
uses
  Classes, SysUtils, LResources, Forms, Controls, Graphics, Dialogs;
 
type
  { Beschreibung TForm1 }
  TForm1 = class(TForm)
  end;
 
var
  { Beschreibung der Variable Form1 }
  Form1: TForm1;
 
//usw...


Ein kleiner Nachteil ergibt sich bei der Deklaration von Feldern/Variablen in einer Aufzählung. So ist es nötig, wenn eine Variable gezielt dokumentiert werden soll, diese einzeln nach dem Kommentar aufzuführen:

Code: Alles auswählen

{ Beschreibung, welche beiden folgenden Variablen zugeordnet wird }
  BesondereVar, Var2: integer
  { Beschreibung BesondereVar }
  BesondereVar,
  { Beschreibung Var2 }
  Var2: integer;


Sollte man es bevorzugen, die Kommentare nach den zu beschreibenden Items zu platzieren, ist dies unter Verwendung von '<' möglich. Dieses Zeichen direkt zu Kommentarbeginn weist PasDoc bei seiner Dokumenterstellung an, das entsprechende Kommentar nicht dem folgenden, sondern dem vorhergehenden Item zuzuordnen:

Code: Alles auswählen

 
unit Unit1;
 
 
 
//< Beschreibung von Unit1
 
interface
 
uses
  Classes, SysUtils, LResources, Forms, Controls, Graphics, Dialogs;
 
type
  TForm1 = class(TForm)  {< Beschreibung TForm1 }
  end;
 
var
  Form1: TForm1;
  {< Beschreibung der Variable Form1 }
 
//usw...


Dieses Beispiel verdeutlicht noch weitere Eigenschaften von PasDoc. So ist es unerheblich, in welcher Syntax die Kommentare markiert werden (natürlich nur so lange, wie sie den Regeln von Pascal entsprechen).
Auch zusätzliche Leerzeichen und Zeilenumbrüche werden von PasDoc ignoriert.

Ebenfalls erwähnt werden muss die Handhabung von aufeinander folgenden einzeiligen Kommentaren, welche durch // eingeleitet werden. Diese Kommentare werden durch PasDoc zusammengefasst und wie ein einzelnes Kommentar in {} gehandhabt.

Treten im Quellcode mehrere Kommentare auf, ohne entsprechende Items dazwischen, so verwendet PasDoc stets nur das letzte gefundene Kommentar und die übrigen werden ignoriert:

Code: Alles auswählen

{ ignoriertes Kommentar }
 
//dieses Kommentar wird
//als ganzes der
//Procedure Foo zugeordnet
procedure Foo;


Formatierungen und Funktionen in den Kommentaren:
  • Überflüssiger Whitespace innerhalb der Kommentare wird ebenfalls (wie beispielsweise auch in html) durch PasDoc zusammengefasst.
  • Paragrafen: die einzige Ausnahme, bei welcher überflüssiger Whitespace nicht entfernt wird, bilden Absätze. Um einen Absatz zu erreichen, ist es nötig, eine Leerzeile in ein Kommentar einzufügen. Dadurch entsteht in der Ausgabe ebenfalls ein Absatz. Das Hinzufügen mehrere Leerzeilen hat allerdings keinen weiteren Einfluss.
  • Bindestriche: '--' erzeugt einen mittellangen Bindestrich, '---' erzeugt einen langen Bindestrich und – bzw. wenn mehrere hintereinander dargestellt werden sollen '@-' erzeugt einen kurzen Bindestrich
  • URLs, wie http://www.lazarusforum.de werden von PasDoc automatisch erkannt und in der Dokumentation als Link dargestellt.

Items ohne entsprechende Kommentare im Quelltext werden standardmäßig dennoch dargestellt. So ist es also nicht nötig, selbsterklärende Dinge nur deshalb zu kommentieren, dass sie entsprechend in die Doku aufgenommen werden.


Dieser Artikel bassiert auf der Originaldokumentation, zu finden unter: http://pasdoc.sipsolutions.net/

Antworten