Vordefinierte Abschnitte und Abschnittstypen

Die folgende Tabelle zeigt alle vordefinierten Abschnitte und schlägt vor wie diese in einem gut strukturierten Sourcecodekommentar verwendet werden können. Wenn Sie ein Anwenderhandbuch schreiben können Sie frei entscheiden, welche Abschnitte Sie für welchen Zweck verwenden, beachten Sie aber, dass nicht alle Abschnitte gleich ausgegeben werden.

Vordefinierte Abschnitte

Abschnittsname	Typ	Zweck
Description	Standard	Enthält die Beschreibung des Themas.
Summary	Summary	Enthält eine Zusammenfassung der Themenbeschreibung.
Notes	Standard	Wird für ein oder mehrere kurze Anmerkungen zum Thema verwendet. Sollte kurz sein.
BemerkungRemarks	Standard	Für spezielle Bemerkungen zum Thema, kann recht lang sein.
Parameters	Parameter Description	Besteht aus einer Liste von Parameterbeschreibungen. Weitere Informationen über Parameterbeschreibungen finden Sie in Beschreiben von Parametern
Returns	Return Description	Enthält eine Beschreibung der Rückgabewerte einer Funktion.
Return Value	Return Values	Enthält eine Liste der Beschreibungen von Rückgabewerte.
Example	Additional Information	Für Beispiele zum Thema das beschrieben wird.
Ignore	Ignored Text	Enthält Text, der in der erzeugten Dokumentation nicht aufscheint.
See Also	See Also List	Enthält entweder eine durch Beistriche getrennte Liste von Themen-IDs, zu denen automatisch Hyperlinks erzeugt werden, oder normalen Text.
Bugs	Standard	Enthält eine Beschreibung der Fehler und Probleme des beschriebenen Objektes.
Internal	Standard	Enthält Dokumentationsteile, die nur den Teammitgliedern zugänglich sein sollten und nicht der Öffentlichkeit.
Todo	Standard	Enthält Text, der beschreibt, welche Teile des beschriebenen Objektes noch unvollständig sind und überarbeitet werden müssen.
Exceptions	Standard	Enthält eine Beschreibung von Ausnahmen, die von einer Funktion oder Methode während der Ausführung ausgegeben werden.
Conditions	Standard	Enthält eine Beschreibung über Vor- und Nachbedingung bestimmter Elemente, zum Beispiel über Vorbedingungen über das Aufrufen von Funktionen.
Author	Standard	Enthält Informationen über den Autor des Themas.
History	Standard	Enthält Informationen über die Entwicklung eines Elementes. Dies kann für jedes Thema verwendet werden, wird aber meistens für Dateien verwendet.
Version	Standard	Enthält Informationen über die Version eines bestimmten Elementes, wie die Versionsnummer und Kompatibilitätsnotizen für ältere Versionen.
Glossary	Glossary Text	Enthält Text für Glossareinträge für ein Thema. Dieser Abschnitt wird in der Ausgabe nicht beim jeweiligen Thema ausgegeben.
Source Description	Implementation Description	Enthält einen beschreibenden Text, der zur Implementierung eines Objektes hinzugefügt wird, wenn dieser in die Dokumentation integriert wird.
Multi Item Glossary	Value Description List	Enthält Glossareinträge und deren Beschreibung. Beide Spalten können in einem Glossar (Bericht) ausgegeben werden. In der Standardeinstellung wird dieser Abschnitt nicht ausgegeben.
Link List	Named Section	Enthält Text oder Hyperlinks und einen Namen für den jeweiligen Abschnitt, als erste Zeichenkette, die vom folgenden Text durch einen Beistrich getrennt wird.

Abschnittstypen

Das ist eine Liste von Abschnittstypen, die Doc-O-Matic zur Verfügung stellt:

Abschnittstyp	Bedeutung
Standard	Text ohne spezielle Bedeutung.
Parameter Description	Text, der die Parameterbeschreibung enthält. Der Abschnitt kann als Liste von Parametern und Ihrer Beschreibung oder als zweispaltige Tabelle ausgegeben werden.
Return Description	Text enthält die Beschreibung der Rückgabewerte.
Return Values	Text enthält die Beschreibung der Rückgabewerte. Der Abschnitt kann als Liste von Rückgabewerten und Ihrer Beschreibung oder als zweispaltige Tabelle ausgegeben werden.
Additional Information	Text enthält zusätzliche Informationen zum Thema. In diesem Abschnitt können Beispiele geben werden. Der Abschnitt wird in den Hilfesystemen zusätzlich auf einer eigenen Seite ausgegeben. Jeder Abschnitt kann individuell benannt werden, indem Sie eine Überschrift als erste Zeichenkette nach dem Abschnittsbeginnzeichen einfügen.
Summary	Text enthält eine kurze Beschreibung des Zweckes des Symbols oder Elements. Dieser Abschnitt kann auch automatisch erzeugt werden.
See Also List	Text enthält entweder eine durch Beistriche getrennte Liste von Themen-IDs verwendet als Liste von verwandten Themen oder normalen Beschreibungstext. Die Themen-ID können auch jeweils in einer eigenen Zeile platziert werden. Der Abschnitt kann in den HTML-Hilfesystemen auf einer eigenen Seite dargestellt werden. Die Beistriche oder Absätze können für die Ausgabe ersetzt werden.
Ignored Text	Text, der von Doc-O-Matic ignoriert wird.
Glossary Text	Text der nicht beim jeweiligen Thema ausgegeben wird, aber für Berichte und Glossare verwendet werden kann.
Implementation Description	Text in diesem Abschnitt wird als Beschreibung derImplementierung einer Funktion oder einer Datei verwendet.
Named Section	Dieser Abschnitt kann individuell benannt werden, indem der Name als erste Zeichenkette im Abschnitt durch einen Beistrich vom restlichen Text getrennt, geschrieben wird. Die Beistriche oder Absätze können für die Ausgabe ersetzt werden.
Value Description List	Text enthält eine Liste von Werten. Der Abschnitt kann als Liste von Werten und Ihrer Beschreibung oder als zweispaltige Tabelle ausgegeben werden.

Automatische erzeugte Abschnitte

Das ist eine Liste von Abschnitten, die Doc-O-Matic automatisch erzeugt, wenn die entsprechenden Elemente in der Dokumentation vorhanden sind.

Abschnitt (Standard)	Abschnitt (VS-Vorlage)	Typ	Optionsseite
Body Source	Body Source	Body Source	Body-Sourcecode
Class Hierarchy	Inheritance Hierarchy	Class Hierarchy	Lokale Klassenhierarchie
Container	Container	Symbol Container	Optionen für den Container-Abschnitt
Pascal, C++, C#, Visual Basic, PHP, MATLAB, JavaScript, IDL, Java	Pascal, C++, C#, Visual Basic, PHP, MATLAB, JavaScript, IDL, Java	Syntax	Syntax in mehreren Sprachen, Optionen für die Syntaxhervorhebung, Abschnitte (Aussehen der Abschnitte)
Links	Links	Topic Links	Anzeige der Navigationslinks (HTML)
Reports	Reports	Reports	Abschnittsformatierung (HTML, PDF und RTF) Tabellenlayout
Overload List	Overload List	Overload List	Inhaltsoptionen
Navigation	Navigation	Topic Navigation	Abschnittsformatierung (HTML, PDF und RTF) Tabellenlayout, Inhaltsoptionen
Members	Members	Member Description Section	Abschnittsoptionen