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;


Last Change: 27.10.2001
© Copyright by Stefan Brüning. All rights reserved