 |
Java-Style Kommentare
Bei der Formatierung von Java-Style Kommentaren wird zwischen Kurzkommentaren
und zeilenübergreifenden
Kommentaren unterschieden.
Formatierung von Kurzkommentaren
Wird ein Kurzkommentar im Quelltext erzeugt oder verändert, kann er
über Kommentare|Kommentar formatieren bzw. den entsprechendenMenüpunkt
des PopUp-Menüs, das über die rechte Maustaste erreichbar ist,
formatiert werden. Zur Formatierung eines Kommentars werden die Projekteinstellungen
(Registerkarte
Sprache/Kommentare) berücksichtigt. Dort kann
konfiguriert werden, in welcher Spalte Kurzkommentare beginnen sollen und
in welcher Spalte Kommentare enden sollen.
Formatierung
von zeilenübergreifenden Kommentaren
Der Aufruf der Formatierung von zeilenübergreifenden Kommentaren erfolgt
analog zu der Formatierung
von Kurzkommentaren. Bei der Formatierung des Kommentartextes werden
aber zusätzlich Kommentar-Tags berücksichtigt, die im Kommentartext
enthalten sind. Dabei wird unterschieden zwischen Tags, die den Typ eines
Kommentars festlegen und Tags, die einzelne Kommentarelemente einleiten.
Die folgende Tabelle enthält alle Tags, die für die Festlegung
des Kommentartyps erlaubt sind.
Tag |
Format / Beschreibung |
@class |
Format: @class Klassenname
Das @class-Tag legt fest, dass eine Klasse kommentiert wird. |
@function |
Format: @function Funktionsname
Das @function-Tag legt fest, dass eine Funktion kommentiert wird. |
@interface |
Format: @interface Interfacebezeichner
Das @interface-Tag legt fest, dass ein Interface kommentiert wird. |
@module |
Format: @module Mudulname
Das @module-Tag legt fest, dass ein Modul kommentiert wird. |
@procedure |
Format: @procedure Prozedurbezeichner
Das @procedure-Tag legt fest, dass eine Prozedur kommentiert wird. |
@struct |
Format: @struct Strukturbezeichner
Das @struct-Tag legt fest, dass eine Struktur kommentiert wird. |
Ein Kommntar darf maximal einen Der in der obigen Tabelle aufgeführten
Tags enthalten. Enthält ein Kommentar kein solches Tag, kann für
diesen Kommentar über Ed42 keine entsprechende HTML-Dokumentation
erzeugt werden. Das ist beispielsweise für Java-Module sinnvoll, die
unter Verwendung des Tools javadoc dokumentiert werden sollen.
Die folgende Tabelle enthält eine vollständige Aufstellung
der Tags, die ein Element eines Kommentars einleiten.
Formatierungs-
kommando |
Format / Beschreibung |
@attribute |
Format: @attribute [(Modus)] Name [: Typ]
[Beschreibung]
Das @attribut-Tag leitet die Beschreibung eines Attributs ein. Die (optionale)
Beschreibung kann mehrere Zeilen enthalten und endet vor dem nächsten
Tag bzw. dem Kommentarende. Die Modus-Angabe (z.B. public, private, ...)
muß in runden Klammern eingeschlossen werden. Der Typ-Angabe muß
das Zeichen ':' vorangehen.
Das @attribute-Tag darf nur in Kommentaren für Klassen verwendet
werden. |
@author |
Format: @author Autor-Bezeichner
Über das @author-Tag kann ein Autor festgelegt werden. Der
Autor-Bezeichner endet am Ende der Kommentarzeile. Ein Kommentar kann mehere
@author-Tags enthalten, deren zugehörige Informationen bei der HTML-Erzeugung
zusammengefaßt werden.
Das @author-Tag darf nur in Kommentaren für Klassen, Interfaces
oder Modulen verwendet werden. |
@change |
Format: @change Datum Name
[Beschreibung]
Über das @change-Tag kann eine Änderung im Quellcode dokumentiert
werden. Die (optionale) Beschreibung der Änderung muß in einer
neuen Zeile beginnen, kann mehrere Zeilen enthalten und endet vor dem nächsten
Tag bzw. dem Kommentarende. Die Datumsangabe darf ausschließlich
aus Ziffern und Punkten bestehen.
Das @change-Tag darf nur in Kommentaren für Klassen, Interfaces
oder Modulen verwendet werden. |
@deprecated |
Format: @deprecated [Beschreibung]
Über das @deprecated-Tag kann eine Funktion markiert werden, die
nur noch aus Gründen der Abwärtskompatibilität vorhanden
ist. Die zugehörige (optionale) Beschreibung endet am Ende der Kommentarzeile. |
@exception |
Format: @exception Typ [Beschreibung]
Über das @exception-Tag wird die Dokumentation einer Exception
eingeleitet, die von einer Funktion bzw. Prozedur geworfen werden kann.
Die zugehörige (optionale) Beschreibung kann mehrere Zeilen umfassen
und endet vor dem nächsten Tag bzw. dem Kommentarende.
Das @exception-Tag darf nur in Kommentaren für Funktionen oder
Prozeduren verwendet werden. |
@implements |
Format: @implements Interfaceliste
Über das @implements-Tag wird eine Liste von Interface-Bezeichnern
eingeleitet, die von einer Klasse implementiert werden. Die Liste endet
am Ende der Kommentarzeile.
Das @implements-Tag darf nur in Kommentaren für Klassen verwendet
werden. |
@inclass |
Format: @inclass Klassenname
Über das @inclass-Tag kann eine Klasse angegeben werden in der
die kommentierte Funktion bzw. Prozedur deklariert ist.
Das @exception-Tag darf nur in Kommentaren für Funktionen oder
Prozeduren verwendet werden. |
@infoimpl |
Format: @infoimpl Implementierungsbeschreibung
Über das @infoimpl-Tag wird eine Information zur Implementierung
eingeleitet. Die Implementierungsbeschreibung kann mehrere Zeilen umfassen
und endet vor dem nächsten Tag bzw. dem Kommentarende.
Das @infoimpl-Tag darf nur in Kommentaren für Klassen, Interfaces,
Funktionen oder Prozeduren verwendet werden. |
@inherits |
Format: @inherits Klassen-/Interface-Liste
Über das @inherits-Tag wird eine Klassen-/Interfaceliste eingeleitet,
von der eine Klasse bzw. ein Interface erbt. Die Liste endet am Ende der
Kommentarzeile.
Das @implements-Tag darf nur in Kommentaren für Klassen oder Interfaces
verwendet werden. |
@method |
Format: @method [(Modus)] Name [Beschreibung]
Das @method-Tag leitet die Beschreibung einer Methode ein. Die (optionale)
Beschreibung kann mehrere Zeilen enthalten und endet vor dem nächsten
Tag bzw. dem Kommentarende. Die Modus-Angabe (z.B. public, private, ...)
muß in runden Klammern eingeschlossen werden.
Das @method-Tag darf nur in Kommentaren für Klassen verwendet werden. |
@param |
Format: @param [(Modus)] Name [: Typ]
[default=Wert] [Beschreibung]
Das @param-Tag leitet die Beschreibung eines Parameters einer Funktion
bzw. einer Prozedur ein. Die (optionale) Beschreibung kann mehrere Zeilen
enthalten und endet vor dem nächsten Tag bzw. dem Kommentarende. Die
Modus-Angabe (z.B. in, out, ...) muß in runden Klammern eingeschlossen
werden. Der Typ-Angabe muß das Zeichen ':' vorangehen.
Das @param-Tag darf nur in Kommentaren für Funktionen oder Prozeduren
verwendet werden. |
@return |
Format: @return Typ [Beschreibung]
Das @return-Tag leitet die Beschreibun gdes Returnwertes einer Funktion
ein. Die Angabe des Typs muß entfallen, wenn in der Definitionsdatei der
zugehörigen Sprache (vgl. Sprachunterstützung)
ein entsprechender Eintrag vorhanden ist (WITHOUT_RETURN_TYPE).
Das @return-Tag darf nur in Kommentaren für Funktionen verwendet
werden. |
@see |
Format: @see Verweis
Das @see-Tag leitet einen Verweis auf eine andere Klasse/Funktion/...
ein. Der Verweis endet am Ende der Kommentarzeile. |
@since |
Format: @since Zeitpunkt
Das @since-Tag leitet eine Angabe ein, die dokumentiert, ab wann (d.h.
ab welcher Version / ab welchem Datum / ...) eine Klasse/Funktion/... existiert. |
@version |
Format: @version Versionsbeschreibung
Über das @version-Tag wird eine Versionsinformation eingeleitet,
die am Ende der Kommentarzeile endet. |
Mit eckigen Klammern umgebene Ausdrücke sind optional.
Behandlung von HTML-Tags
Die Texte innerhalb eines zeilenübergreifenden Kommentars können
HTML-Tags enthalten, die der Formatierung der Kommentartexte berücksichtigt
werden. Dabei wird unterschieden zwischen
-
HTML-Tags, die in einer Zeile alleine stehen,
-
HTML-Tags, die am Zeilenbeginn stehen müssen,
-
HTML-Tags, die eine Zeile abschließen und
-
HTML-Tags, die im Text an einer beliebige Position stehen können.
Diese Klassifizierung wird über die Datei htmlcmds.txt vorgenommen.
Diese Datei muß folgende Angaben enthalten:
-
Liste der HTML-Tags, die in einer Zeile alleine stehen sollen. Die Liste
muß über zwei Zeilen mit Inhalt '***SINGLELINECOMMANDS' bzw.
'***END' geklammert werden.
-
Liste der HTML-Tags, die am Anfang einer Zeile stehen sollen. Die Liste
muß über zwei Zeilen mit Inhalt '***STARTLINECOMMANDS' bzw.
'***END' geklammert werden.
-
Liste der HTML-Tags, die eine Zeile abschließen. Die Liste muß
über zwei Zeilen mit Inhalt '***ENDLINECOMMANDS' bzw. '***END' geklammert
werden.
-
Liste der HTML-Tags, die an einer beliebigen Position stehen können.
Die Liste muß über zwei Zeilen mit Inhalt '***NORMALCOMMANDS'
bzw. '***END' geklammert werden.
Bei der Generierung von HTML-Dokumentation
werden die in den Kommentartexten enthaltenen HTML-Tags ohne Änderung
weitergegeben. Daraus ergibt sich unmittelbar die Forderung, dass Kommentartexte
keine HTML-Tags enthalten sollten, die Auswirkungen auf die Struktur eines
Dokumentes haben, wie z.B. <h1>, <h2> usw.
Ersetzen von Umlauten
Sowohl für einfache als auch für strukturierte Kommentare bietet
Ed42 die Möglichkeit an, alle Umlaute in Kommentaren zu ersetzen,
bevor sie in den Quellcode eingearbeitet werden. Das Feature kann über
die Projektoptionen (Registerkarte Sprache/Kommentare)
aktiviert werden.
Einfügen von Leerzeilen
Über die Spracheinstellungen (d.h.
die zu den Sprachen gehörigen Definitionsfiles) kann eingestellt werden,
dass zur besseren Lesbarkeit von Kommentaren im Quellcode zusätzliche
Leerzeilen eigefügt werden.
Beispiele
Die folgenden Programmfragmente enthalten einen Klassen- und einen Fuktions-Kommentar.
/*
* @class TestListener
* Die Klasse TestListener horcht auf Port 3456 auf Nachrichten
des Browsers.
* @attribute cmdfeld
* Textfeld, in dem die Nachrichten des
Browsers angezeigt werden.
* @method main
* Main-Routine
* @method Testlistener
* Konstruktor; erzeugt ein Fenster mit
einem Textfeld.
*/
public class TestListener extends CloseableFrame
{
static TextField cmdfeld;
public static void main(String[] args)
{
...
}
public TestListener(String title)
{
super(title);
...
}
}
/*
* @function Test
* Die Testfunktion hat zwei Argumente und gibt einen String
zurueck.
* @param a : integer
* Erster Parameter: Ein Integerwert.
* @param b : string
* Zweiter Parameter: Ein String.
* @return string
* Der Returnwert ist eine Zeichenkette.
*/
function Test(a : integer; b : string) : string;
begin
...
end;
|