Hallo,
ich bin gerade dabei, mich mit Quelltextdokumentation mittels
XML-Kommentaren zu beschäftigen. Es wird überall über die Kommentierung von Methoden geschrieben. Die Kommentierung einer Klasse oder Konstante scheint genauso zu funktionieren (Help Insight reagiert), aber wie sieht es mit der Kommentierung der
Unit als Ganzes oder einer Variablen aus? Gibt es dafür andere standardisierte
XML-Formate, oder reagiert Help Insight einfach nur nicht darauf und die Formate sind gleich?
Ich möchte folgende Sachen dokumentieren:
- Intuition und Verwendung des Moduls (Zusammenspiel der public Methoden und Klassen) -> in der entsprechenden Unit, z.B. vor dem interface-Abschnitt
- Intuition und Verwendung einer Klasse -> direkt vor ihrer Deklaration (Format geklärt)
- Verwendung von Methoden, Prozeduren und Funktionen -> direkt vor ihrer Deklaration (Format geklärt)
- Bedeutung und Verwendung von Variablen -> dort, wo die Variablen deklariert sind (var-Abschnitt oder Klassendeklaration)
- Interne Funktionsweise des Moduls (Zusammenspiel der private Methoden und Hilfsklassen) -> in der entsprechenden Unit, z.B. am Anfang des implementation-Abschnitts
- Interne Funktionsweise von Methoden, Prozeduren und Funktionen -> in der Implementierung der Methode, Prozedur oder Funktion (Klartext, wird ausschließlich im Code benötigt)
Dabei möchte ich mich natürlich an ggf. bestehende etabliete Formate, wie z.B. die
XML-Kommentare über Methodendeklarationen halten. Wenn die Anordnung der Kommentare in euren Augen unsinnig ist, bitte ich um Begründungen bzw. Alternativen, wo diese Kommentare üblicherweise zu finden sind.
"Seit er seinen neuen Computer hat, löst er alle seine Probleme, die er vorher nicht hatte."