Richtlinien für Kommentare
W
willy
Themenstarter:in
Richtlinien für Kommentare
Hallo Leute,
Gibt es bestimmten Richtlinien die man beachten muss, wenn man eine Methode Kommentieren muss??
Z.B: Methodenparameter, rückgabewerte und was die methode eigentlich tut.
Wie ist es zu in C# anzuordnen
Beispiel:
/**
* Diese Methode mach dies und das
**/
private string getFileContent(string path)
{
}
Wo werden wie geasagt rückgabewert und parameter plaziert???
MfG
Willy
C#, einfach geil 8)
L
Wenn Du statt der Java-Syntax für Kommentare die .NET-/C#-/MS- (oder wie auch immer die heißt) Syntax verwendest, in der Methoden- und Klassenbeschreibungen mit /// anfangen, dann müssten Dir Visual Studio oder #Develop schon die entsprechenden Kommnetarschablone erzeugen...
Sarkusmus ist, wenn nichts mehr hilft, außer Lachen.
Du solltest Dich nach der Methode richten, die Du verwendest, wie Lord Hessia sagte..
Hier mal ein Beispiel für Doxygen-Code-Blöcke
http://www.stack.nl/~dimitri/doxygen/docblocks.html
Dort kann man sehen, wie bspw. returns in Methoden gekennzeichnet werden.
Hallo willy,
hier ein älteres (.NET 1.1) aber vermutlich ansonsten ziemlich vollständiges Beispiel:
using System;
namespace DokumentationBeispiel
{
//**************************************************************************
/// <summary>
/// <meta>
/// <para>Stack-Klasse als Dokumentationsbeispiel
/// </para>
/// <para>Die Texte, die die Dokumentation dokumentieren, sind
/// in grün geschrieben, die eigentliche Dokumentation in schwarz.
/// </para>
/// </meta>
/// Stellt eine einfache LIFO-Auflistung (Last-In-First-Out) von
/// Objekten dar.
/// <meta><para>|Abschnitt erforderlich|</para></meta>
/// </summary>
///
/// <meta>Die Beispielklasse ist formal korrekt dokumentiert und zeigt für
/// mindestens eine Member pro Memberart alle Dokumentationsmöglichkeiten
/// auf.
/// </meta>
/// <para>Ein Stack ist eine Collection, auf die der Zugriff nach dem LIFO
/// (Last In, Fist Out) Prinzip erfolgt.
/// </para>
/// <para>Zu Beachten ist, dass die Methode <c><see cref="Stack.Pop"/></c>
/// das Element nicht zurückliefert sondern nur entfernt. Der Zugriff
/// auf das oberste Element erfolgt mit <c><see cref="Stack.Peek"/></c>.
/// </para>
/// <para>Der Stack wächst dynamisch, wenn mehr Elemente hinzugefügt
/// werden als seine momentane Kapazität.
/// </para>
/// <meta><para>|Abschnitt empfohlen|</para></meta>
///
/// <example>
/// Im folgenden Beispiel wird das Erstellen und Hinzufügen von Werten für
/// Stack sowie der Zugriff auf das obersten Elements dargestellt.
/// <code>
/// // Erzeugt und initialisiert den neuen Stack.
/// Stack stkBsp = new Stack();
/// stkBsp.<see cref="Stack.Push(Object)">Push</see> ("Hello");
/// stkBsp.Push ("World");
/// stkBsp.Push ("!");
///
/// // Zeigt einige Informationen an
/// Console.WriteLine ( "stkBsp:" );
/// Console.WriteLine ( " Count: " + stkBsp.<see cref="Stack.Count">Count</see>);
/// Console.WriteLine ( " Oberstes: " + stkBsp.<see cref="Stack.Peek">Peek</see> ();
///
/// // Entfernt alle Elemente wieder
/// stkBsp.<see cref="Stack.Pop">Pop</see> ();
/// stkBsp.Pop ();
/// stkBsp.Pop ();
/// </code>
/// <meta><para>|Abschnitt optional|</para></meta>
/// </example>
/// <remarks>
/// <c>Stack</c> wird als zirkulärer Puffer implementiert.
/// <meta>
/// <para>Nicht erlaubt für Typen sind folgende Abschnitte:</para>
/// <list type="bullet">
/// <item><description><exception></description></item>
/// <item><description><param></description></item>
/// <item><description><returns></description></item>
/// <item><description><value></description></item>
/// </list>
/// <para>|Abschnitt optional|</para>
/// </meta>
/// </remarks>
///
/// <seealso><meta>Wenn bei <see> oder <seealso> kein
/// Verweistext angegeben wird, wird automatisch der Verweis selbst
/// als Text verwendet. Das spart Tippaufwand und vermeidet die
/// Inkonsistenz zwischen dem Verweistext und dem Verweis selbst</meta></seealso>
/// <seealso cref="Stack.Push(Object)"/>
/// <seealso cref="Stack.Pop"/>
/// <seealso cref="Stack.Peek"/>
/// <seealso><meta>Die selben Verweise mit Verweistext:</meta></seealso>
/// <seealso cref="Stack.Push(Object)">Push-Methode</seealso>
/// <seealso cref="Stack.Pop">Pop-Methode</seealso>
/// <seealso cref="Stack.Peek">Peek-Methode</seealso>
/// <seealso><meta>|Abschnitt optional|</meta></seealso>
public class Stack
{
//-----------------------------------------------------------------------
/// <summary>
/// Der Speicherort für die Stack-Elemente.
/// <meta><para>|Abschnitt erforderlich|</para></meta>
/// </summary>
/// <value>
/// Die Stack-Elemente werden in einen Object-Array gespeichert.
/// <meta><para>|Abschnitt optional|</para></meta>
/// </value>
///
/// <para>Das Object-Array wird nur durch die Methoden
/// <see cref="Stack.Push(Object)"/> und <see cref="Stack.Pop"/>
/// verändert.</para>
/// <meta><para>|Abschnitt optional|</para></meta>
///
/// <example>
/// <meta><para>|Abschnitt optional|</para></meta>
/// </example>
/// <remarks>
/// <meta>
/// Das Array ist nicht dynamisch und deshalb muss bei
/// Kapazitätsanpassungen ein neues (größeres) Array erzeugt werden.
/// <para>Nicht erlaubt für Felder sind folgende Abschnitte:</para>
/// <list type="bullet">
/// <item><description><exception></description></item>
/// <item><description><param></description></item>
/// <item><description><returns></description></item>
/// </list>
/// </meta>
/// <meta><para>|Abschnitt optional|</para></meta>
/// </remarks>
/// <seealso cref="Stack"/>
/// <seealso><meta>|Abschnitt optional|</meta></seealso>
private Object[] aobjStack;
private int iStackPointer;
//=======================================================================
/// <summary>
/// Konstruktor
/// <meta><para>|Abschnitt erforderlich|</para></meta>
/// </summary>
///
/// <para>Initialisiert ein neues <c>Stack</c>-Objekt mit einer festgelegten
/// Startkapazität.</para>
/// <meta><para>|Abschnitt empfohlen|</para></meta>
///
/// <example>
/// Siehe Beispiel unter <see cref="Stack"/>
/// <meta><para>|Abschnitt optional|</para></meta>
/// </example>
/// <remarks>
/// Die Startkapazität kann bei <c>Stack.Stack (int)</c>
/// übergeben werden.
/// <meta>
/// <para>Nicht erlaubt für Konstruktoren sind folgende Abschnitte:</para>
/// <list type="bullet">
/// <item><description><returns></description></item>
/// <item><description><value></description></item>
/// </list>
/// </meta>
/// <meta><para>|Abschnitt optional|</para></meta>
/// </remarks>
/// <seealso cref="Stack"/>
/// <seealso>Stack.Stack(int)</seealso>
/// <seealso><meta>|Abschnitt optional|</meta></seealso>
public Stack ()
{
aobjStack = new Object [20]; // Implementierung unvollständig
iStackPointer = -1;
}
//=======================================================================
/// <summary>
/// Konstruktor
/// <meta><para>|Abschnitt erforderlich|</para></meta>
/// </summary>
///
/// <para>Initialisiert ein neues <c>Stack</c>-Objekt mit der übergebenen
/// Startkapazität.
/// </para>
/// <meta><para>|Abschnitt empfohlen|</para></meta>
/// <param name="iSize">Startkapazität in Anzahl der aufzunehmenden Objekte
/// </param>
///
/// <example>
/// <meta><para>|Abschnitt optional|</para></meta>
/// </example>
/// <remarks>
/// <meta>
/// <para>Nicht erlaubt für Konstruktoren sind folgende Abschnitte:</para>
/// <list type="bullet">
/// <item><description><returns></description></item>
/// <item><description><value></description></item>
/// </list>
/// </meta>
/// <meta><para>|Abschnitt optional|</para></meta>
/// </remarks>
/// <seealso cref="Stack"/>
/// <seealso>Stack.Stack</seealso>
/// <seealso><meta>|Abschnitt optional|</meta></seealso>
public Stack (int iSize)
{
aobjStack = new Object [iSize]; // Implementierung unvollständig
iStackPointer = -1;
}
//=======================================================================
/// <summary>
/// Fügt ein Objekt oben auf dem <c>Stack</c> ein.
/// <meta><para>|Abschnitt erforderlich|</para></meta>
/// </summary>
/// <param name="obj">Das <c>Object</c>,
/// das in <c>Stack</c> abgelegt werden soll (darf null sein).
/// <meta><para>|Abschnitt stark empfohlen, wenn Parameter vorhanden|</para></meta>
/// </param>
/// <exception member="System.OutOfMemoryException">Kein Speicher, um
/// die Operation auszuführen
/// </exception>
/// <exception member="DokuBsp.PushException">Operation kann nicht
/// beendet werden
/// </exception>
/// <meta><para>|Abschnitt empfohlen|</para></meta>
/// <example>
/// <meta><para>|Abschnitt optional|</para></meta>
/// </example>
/// <remarks>
/// <para>Wenn die momentane Kapazität des Stacks nicht ausreicht, um das
/// Element aufzunehmen, wird die Kapazität erhöht.
/// </para>
/// <meta>
/// <para>Nicht erlaubt für Methoden sind folgende Abschnitte:</para>
/// <list type="bullet">
/// <item><description><value></description></item>
/// </list>
/// </meta>
/// Das übergebene Objekt <paramref name="obj"/> darf <c>null</c> sein.
/// <meta><para>|Abschnitt optional|</para></meta>
/// </remarks>
/// <seealso cref="Stack"/>
/// <seealso cref="Stack.Pop"/>
/// <seealso cref="Stack.Peek"/>
/// <seealso><meta>|Abschnitt optional|</meta></seealso>
/// <permissionx cref="System.Security.PermissionSet">
/// <meta>Die Verwendung von <permission> ist noch nicht festgelegt</meta>.
/// Jeder kann auf diese Methode zugreifen.
/// </permissionx>
public void Push (Object obj) {
aobjStack [++iStackPointer] = obj; // Implementierung unvollständig
}
//=======================================================================
/// <summary>
/// Entfernt das oberste Objekt aus <c>Stack</c>.
/// <meta><para>|Abschnitt erforderlich|</para></meta>
/// </summary>
/// <exception member="System.InvalidOperationException">
/// Wenn der <c>Stack</c> leer ist.
/// </exception>
///
/// <meta><para>|Abschnitt empfohlen|</para></meta>
///
/// <example>
/// <meta><para>|Abschnitt optional|</para></meta>
/// </example>
/// <remarks>
/// <para>Das entfernte Objekte wird nicht zurückgeliefert (siehe
/// <see cref="Stack.Peek"/>)
/// </para>
/// <meta>
/// <para>Nicht erlaubt für Methoden sind folgende Abschnitte:</para>
/// <list type="bullet">
/// <item><description><value></description></item>
/// </list>
/// </meta>
/// <meta><para>|Abschnitt optional|</para></meta>
/// </remarks>
/// <seealso cref="Stack"/>
/// <seealso cref="Stack.Push(Object)"/>
/// <seealso cref="Stack.Peek"/>
/// <seealso><meta>|Abschnitt optional|</meta></seealso>
public void Pop () {
--iStackPointer; // Implementierung unvollständig
}
//=======================================================================
/// <summary>
/// Gibt das oberste Objekt von <c>Stack</c> zurück, ohne es zu entfernen.
/// <meta><para>|Abschnitt erforderlich|</para></meta>
/// </summary>
/// <returns>Das oberste Object von Stack.
/// <meta><para>|Abschnitt stark empfohlen, wenn ein Rückgabewert vorhanden|</para></meta>
/// </returns>
/// <exception member="System.InvalidOperationException">
/// Wenn der <c>Stack</c> leer ist.
/// </exception>
///
/// <meta><para>|Abschnitt empfohlen|</para></meta>
///
/// <example>
/// <meta><para>|Abschnitt optional|</para></meta>
/// </example>
/// <remarks>
/// <para>Das zurückgelieferte Objekte wird nicht entfernt (siehe
/// <see cref="Stack.Pop"/>)
/// </para>
/// <meta>
/// <para>Nicht erlaubt für Methoden sind folgende Abschnitte:</para>
/// <list type="bullet">
/// <item><description><value></description></item>
/// </list>
/// </meta>
/// <meta><para>|Abschnitt optional|</para></meta>
/// </remarks>
/// <seealso cref="Stack"/>
/// <seealso cref="Stack.Push(Object)"/>
/// <seealso cref="Stack.Pop"/>
/// <seealso><meta>|Abschnitt optional|</meta></seealso>
public Object Peek () {
return aobjStack [iStackPointer]; // Implementierung unvollständig
}
//=======================================================================
/// <summary>
/// Anzahl der Elemente
/// <meta><para>|Abschnitt erforderlich|</para></meta>
/// </summary>
/// <value>
/// Die Anzahl der Elemente, die in <c>Stack</c> enthalten sind.
/// <meta><para>|Abschnitt optional|</para></meta>
/// </value>
///
/// <meta><para>|Abschnitt optional|</para></meta>
///
/// <example>
/// <meta><para>|Abschnitt optional|</para></meta>
/// </example>
/// <remarks>
/// <meta>
/// <para>Nicht erlaubt für Eigenschaften sind folgende Abschnitte:</para>
/// <list type="bullet">
/// <item><description><exception></description></item>
/// <item><description><param></description></item>
/// <item><description><returns></description></item>
/// </list>
/// </meta>
/// <meta><para>|Abschnitt optional|</para></meta>
/// </remarks>
/// <seealso cref="Stack"/>
/// <seealso><meta>|Abschnitt optional|</meta></seealso>
public int Count
{
get { return iStackPointer + 1; }
}
}
//**************************************************************************
/// <summary>
/// <meta>Unterklasse um zu zeigen, wie an welchen Stellen verweise auf die
/// Oberklassse sinnvoll sind.</meta>
/// <meta>......................</meta>
/// </summary>
public class ProgramStack : Stack
{
}
//**************************************************************************
/// <summary>
/// <para>ListenBeispiel</para>
/// <para><meta>Die Klasse, ist nur definiert, damit das folgende Beispiel
/// einen Platz hat :-)</meta></para>
/// </summary>
///
/// Abschnitte wie <param> oder <exception> werden automatisch
/// also Listen formatiert. In "unstrukturierten" Abschnitten wie
/// <remarks> können Listen jedoch sinnvoll sein, um bestimmte
/// Informationen aufzubereiten.
///
/// <example>
/// Die Grundstruktur aller Listen hat folgendes Aussehen:
/// <code>
/// <list type="bullet" | "number" | "table">
/// <listheader>
/// <term>term</term>
/// <description>description</description>
/// </listheader>
/// <item>
/// <term>term</term>
/// <description>description</description>
/// </item>
/// </list>
/// </code>
/// </example>
/// <remarks>
/// <para>Für Listen und Tabellen werden die folgenden Tags verwendet:</para>
/// <list type="bullet">
/// <item><description><list></description></item>
/// <item><description><listheader></description></item>
/// <item><description><item></description></item>
/// <item><description><term></description></item>
/// <item><description><description></description></item>
/// </list>
/// <para>Dabei werden nicht in allen Listenarten alle Tags verwendet (z.B.
/// <term> nicht in nummerierten Listen).</para>
/// <para>Außerdem können die Tags in den unterschiedlichen Listen
/// unterschiedlich oft vorkommen. (z.B. <description>
/// mehr als einmal pro <item> in Tabellen.</para>
/// </remarks>
/// <seealso cref="DefinitionslisteMitKopf">Definitionsliste mit Kopf</seealso>
/// <seealso cref="DefinitionslisteOhneKopf">Definitionsliste ohne Kopf</seealso>
/// <seealso cref="Aufzaehlungsliste">Aufzählungsliste</seealso>
/// <seealso cref="NummerierteListe">Nummerierte Liste</seealso>
/// <seealso cref="Tabelle">Tabelle</seealso>
public class ListenBeispiel
{
//***********************************************************************
/// <summary>
/// Definitionsliste mit Kopf
/// </summary>
/// <para>Eignet sich für die Beschreibung von verschiedenen Werten oder Begriffen</para>
/// <example>
/// <para>So sieht der Code aus:</para>
/// <code>
/// <list>
/// <listheader>
/// <term>Wert</term>
/// <description>Bedeutung</description>
/// </listheader>
/// <item>
/// <term>null</term>
/// <description>Die Variable enthält keinen Verweis/kein Objekt.</description>
/// </item>
/// <item>
/// <term>obj</term>
/// <description>Die Variable enthält einen Verweis auf das Objekt obj.</description>
/// </item>
/// </list>
/// </code>
/// <para>Und so das Ergebnis:</para>
/// <list>
/// <listheader>
/// <term>Wert</term>
/// <description>Bedeutung</description>
/// </listheader>
/// <item>
/// <term>null</term>
/// <description>Die Variable enthält keinen Verweis/kein Objekt.</description>
/// </item>
/// <item>
/// <term>obj</term>
/// <description>Die Variable enthält einen Verweis auf das Objekt obj.</description>
/// </item>
/// </list>
/// </example>
/// <remarks>
/// Für Definitionsliste mit Kopf gelten folgende Bedingungen:
/// <list type="bullet">
/// <item><description><list> enthält keine type-Angabe.</description></item>
/// <item><description><listheader> muss genau einmal angegeben werden.</description></item>
/// <item><description><item> kann beliebig oft verwendet werden.</description></item>
/// <item><description><term> muss genau einmal in <listheader> und genau einmal in jedem <item> angegeben werden.</description></item>
/// <item><description><description> muss genau einmal in <listheader> und genau einmal in jedem <item> angegeben werden.</description></item>
/// </list>
/// </remarks>
/// <seealso cref="DefinitionslisteOhneKopf">Definitionsliste ohne Kopf</seealso>
/// <seealso cref="Aufzaehlungsliste">Aufzählungsliste</seealso>
/// <seealso cref="NummerierteListe">Nummerierte Liste</seealso>
/// <seealso cref="Tabelle">Tabelle</seealso>
public class DefinitionslisteMitKopf
{
}
//***********************************************************************
/// <summary>
/// Definitionsliste ohne Kopf
/// </summary>
///
/// <para>Eignet sich die Definition von Begriffen.</para>
///
/// <example>
/// <para>So sieht der Code aus:</para>
/// <code>
/// <para>Verwendete Definition:</para>
/// <list>
/// <item>
/// <term>Aufzählungsliste</term>
/// <description>Eine einfache Liste mit einem Spiegelstrich (bullet) vor jedem Listenelement.</description>
/// </item>
/// <item>
/// <term>Nummerierte Liste</term>
/// <description>Eine einfache Liste mit einer Zahl vor jedem Listenelement, beginnend mit 1 vor dem ersten Element, 2 vor dem zweiten usw.</description>
/// </item>
/// </list>
/// </code>
/// <para>Und so das Ergebnis:</para>
/// <para>Verwendete Definition:</para>
/// <list>
/// <item>
/// <term>Aufzählungsliste</term>
/// <description>Eine einfache Liste mit einem Spiegelstrich (bullet) vor jedem Listenelement.</description>
/// </item>
/// <item>
/// <term>Nummerierte Liste</term>
/// <description>Eine einfache Liste mit einer Zahl vor jedem Listenelement, beginnend mit 1 vor dem ersten Element, 2 vor dem zweiten usw.</description>
/// </item>
/// </list>
/// </example>
/// <remarks>
/// Für Definitionsliste ohne Kopf gelten folgende Bedingungen:
/// <list type="bullet">
/// <item><description><list> enthält keine type-Angabe.</description></item>
/// <item><description><listheader> darf nicht angegeben werden.</description></item>
/// <item><description><item> kann beliebig oft verwendet werden.</description></item>
/// <item><description><term> muss genau einmal in jedem <item> angegeben werden.</description></item>
/// <item><description><description> muss genau einmal in jedem <item> angegeben werden.</description></item>
/// </list>
/// </remarks>
/// <seealso cref="DefinitionslisteMitKopf">Definitionsliste mit Kopf</seealso>
/// <seealso cref="Aufzaehlungsliste">Aufzählungsliste</seealso>
/// <seealso cref="NummerierteListe">Nummerierte Liste</seealso>
/// <seealso cref="Tabelle">Tabelle</seealso>
public class DefinitionslisteOhneKopf
{
}
//***********************************************************************
/// <summary>
/// Aufzählungsliste
/// </summary>
///
/// <para>Eignet sich für einfache Listen, bei der es keine festgelegte Reihenfolge der Einträge gibt.</para>
///
/// <example>
/// <para>So sieht der Code aus:</para>
/// <code>
/// <para>C#-Schlüsselworte:</para>
/// <list type="bullet">
/// <item><description>abstract</description></item>
/// <item><description>as</description></item>
/// <item><description>base</description></item>
/// <item><description>bool</description></item>
/// <item><description>break</description></item>
/// <item><description>byte</description></item>
/// <item><description>case</description></item>
/// <item><description>und noch 70 weitere</description></item>
/// </list>
/// </code>
/// <para>Und so das Ergebnis:</para>
/// <para>C#-Schlüsselworte:</para>
/// <list type="bullet">
/// <item><description>abstract</description></item>
/// <item><description>as</description></item>
/// <item><description>base</description></item>
/// <item><description>bool</description></item>
/// <item><description>break</description></item>
/// <item><description>byte</description></item>
/// <item><description>case</description></item>
/// <item><description>und noch 70 weitere</description></item>
/// </list>
/// </example>
/// <remarks>
/// Für Aufzählungslisten gelten folgende Bedingungen:
/// <list type="bullet">
/// <item><description><list> enthält die type-Angabe 'bullet'.</description></item>
/// <item><description><listheader> darf nicht angegeben werden.</description></item>
/// <item><description><item> kann beliebig oft verwendet werden.</description></item>
/// <item><description><term> darf nicht angegeben werden.</description></item>
/// <item><description><description> muss genau einmal in jedem <item> angegeben werden.</description></item>
/// </list>
/// </remarks>
/// <seealso cref="DefinitionslisteMitKopf">Definitionsliste mit Kopf</seealso>
/// <seealso cref="DefinitionslisteOhneKopf">Definitionsliste ohne Kopf</seealso>
/// <seealso cref="NummerierteListe">Nummerierte Liste</seealso>
/// <seealso cref="Tabelle">Tabelle</seealso>
public class Aufzaehlungsliste
{
}
//***********************************************************************
/// <summary>
/// Nummerierte Liste
/// </summary>
///
/// <para>Eignet sich für einfache Listen, bei der die Reihenfolge der Einträge wichtig ist.</para>
///
/// <example>
/// <para>So sieht der Code aus:</para>
/// <code>
/// <para>Zum erstmaligen Starten der Anwendung:</para>
/// <list type="number">
/// <item><description>Ohrenschützer aufsetzten</description></item>
/// <item><description>Computer einschalten</description></item>
/// <item><description>Mit Benutzerkennung und Passwort anmelden</description></item>
/// <item><description>Verknüpfung der Anwendung doppelklicken</description></item>
/// <item><description>Staunen</description></item>
/// </list>
/// </code>
/// <para>Und so das Ergebnis:</para>
/// <para>Zum erstmaligen Starten der Anwendung:</para>
/// <list type="number">
/// <item><description>Ohrenschützer aufsetzten</description></item>
/// <item><description>Computer einschalten</description></item>
/// <item><description>Mit Benutzerkennung und Passwort anmelden</description></item>
/// <item><description>Verknüpfung der Anwendung doppelklicken</description></item>
/// <item><description>Staunen</description></item>
/// </list>
/// </example>
/// <remarks>
/// Für nummerierte Listen gelten folgende Bedingungen:
/// <list type="bullet">
/// <item><description><list> enthält die type-Angabe 'number'.</description></item>
/// <item><description><listheader> darf nicht angegeben werden.</description></item>
/// <item><description><item> kann beliebig oft verwendet werden.</description></item>
/// <item><description><term> darf nicht angegeben werden.</description></item>
/// <item><description><description> muss genau einmal in jedem <item> angegeben werden.</description></item>
/// </list>
/// </remarks>
/// <seealso cref="DefinitionslisteMitKopf">Definitionsliste mit Kopf</seealso>
/// <seealso cref="DefinitionslisteOhneKopf">Definitionsliste ohne Kopf</seealso>
/// <seealso cref="Aufzaehlungsliste">Aufzählungsliste</seealso>
/// <seealso cref="Tabelle">Tabelle</seealso>
public class NummerierteListe
{
}
//***********************************************************************
/// <summary>
/// Tabellen
/// </summary>
///
/// <para>Eignet sich für tabelarische Informationen.</para>
///
/// <example>
/// <para>So sieht der Code aus:</para>
/// <code>
/// <para>Beispiel für Versicherte:</para>
/// <list type="table">
/// <listheader>
/// <description>VersNr</description>
/// <description>Name</description>
/// <description>Vorname</description>
/// </listheader>
/// <item>
/// <description>1234567</description>
/// <description>Maier</description>
/// <description>Michael</description>
/// </item>
/// <item>
/// <description>7654321</description>
/// <description>Schulze</description>
/// <description>Peter</description>
/// </item>
/// </list>
/// </code>
/// <para>Und so das Ergebnis:</para>
/// <para>Beispiel für Versicherte:</para>
/// <list type="table">
/// <listheader>
/// <description>VersNr</description>
/// <description>Name</description>
/// <description>Vorname</description>
/// </listheader>
/// <item>
/// <description>1234567</description>
/// <description>Maier</description>
/// <description>Michael</description>
/// </item>
/// <item>
/// <description>7654321</description>
/// <description>Schulze</description>
/// <description>Peter</description>
/// </item>
/// </list>
/// </example>
/// <remarks>
/// Für Tabellen gelten folgende Bedingungen:
/// <list type="bullet">
/// <item><description><list> enthält die type-Angabe 'table'.</description></item>
/// <item><description><listheader> darf nicht oder genau einmal angegeben werden.</description></item>
/// <item><description><item> kann beliebig oft verwendet werden. Durch <item> werden die Zeilen der Tabelle gebildet.</description></item>
/// <item><description><term> darf nicht angegeben werden.</description></item>
/// <item><description><description> muss mindestens einmal in jedem <item> und - falls vorhanden - mindestens einmal in <listheader> angegeben werden. In jedem <item> und - falls vorhanden - in <listheader> sollte die selbe Anzahl <description> angegeben werden. Durch <description> werden die Spalten der Tabelle gebildet.</description></item>
/// </list>
/// </remarks>
/// <seealso cref="DefinitionslisteMitKopf">Definitionsliste mit Kopf</seealso>
/// <seealso cref="DefinitionslisteOhneKopf">Definitionsliste ohne Kopf</seealso>
/// <seealso cref="Aufzaehlungsliste">Aufzählungsliste</seealso>
/// <seealso cref="NummerierteListe">Nummerierte Liste</seealso>
public class Tabelle
{
}
}
//**************************************************************************
/// <summary>
/// <meta>Klasse mit minimaler Doku, aber <summary> muss sein</meta>
/// </summary>
public class MinimalDoku
{
}
}
herbivore
R
Nehmen wir an, wir haben eine Methode a(string s), die eine bestimmte Exception werfen kann und deshalb auch im Methodenkommentar eine Zeile mit dem <exception>-Tag hat.
Nehmen wir weiterhin an, wir haben eine Methode a(), die a(string) überlädt und intern a(null) aufruft. Sollte man dann für a() ebenfalls die Exception-Kommentarzeile angeben, obwohl a() nicht explizit diese Exception wirft? Oder sollte man in a() die Exception-Kommentarzeile weglassen, so wie in dem Beispiel:
/// <summary>
/// Holt einen int.
/// </summary>
/// <returns>Ein int.</returns>
int a()
{
return a(null);
}
/// <summary>
/// Holt einen int.
/// </summary>
/// <param name="s">Ein String.</param>
/// <returns>Ein int.</returns>
/// <exception cref="MyException">Wenn ....</exception>
int a(string s)
{
...
throw new MyException(...);
}
T
Meiner Meinung nach muss auch bei den Methodenkommentaren von a() stehen das eine Exception auftreten kann.
Denn für den Anwender dieser Funktion spielt es keine Rolle ob die Funktion die Exception selber wirft oder ob sie weitergeleitet wurde, das Resultat ist ja das selbe.
Und die Methodenkommentare dienen ja zur Information des Anwenders, also gehört es meiner Meinung nach rein
Hallo retnug,
richtig. Es ist ja für den Anwender nicht ersichtlich, welche Überladung welche andere aufruft oder ob alle Überladungen unabhängig voneinander implementiert sind. Das sollte er auch gar nicht wissen, denn die Implementierung einer Methode geht ihn ja auch sowieso nichts an. Es sollten daher immer alle Exceptions die direkt oder indirekt auftreten können, dokumentiert werden.
herbivore
Allerdings würde ich auch nicht zu penibel sein und alles angegeben was jemals irgendwann auftreten könnte. Es macht beispielsweise für mich keinen Sinn, dass ich überall in Doku die ArgumentNullException angebe, wo ich ein Objektinstanz erwarte und es aber bereits schon in der Parameterbeschreibung enthalten ist, das eine Instanz erwartet wird.
Weiterhin wäre es auch absolut überflüssiges über alle eine MemoryException anzugeben, weil es ja möglich wäre, dass der Speicher wirklich mal nicht für eine Stino-Funktion ausreicht.
Nur die Exceptions sind sinnvoll mit der der Programmier bei der Verwendung mit der Bibliothek/Funktion auch was anfangen kann und diese bei Bedarf behandeln könnte.
Es gibt 3 Arten von Menschen, die die bis 3 zählen können und die, die es nicht können...
..., weil es ja möglich wäre, dass der Speicher wirklich mal nicht für eine Stino-Funktion ausreicht.
Eine was? "Stino-Funktion"? Was ist das?
Wissensvermittler und Technologieberater
für .NET, Codequalität und agile Methoden
Eine Funktion die nicht viel Speicher reserviert, sondern einfach weil der Speicher bereits voll ist einen Fehler schmeißt.
Es gibt 3 Arten von Menschen, die die bis 3 zählen können und die, die es nicht können...
R
@ths , @herbivore: Ja, das habe ich fast schon befürchtet. Ist ja eigentlich auch logisch. Und betrifft nicht nicht Überladungen sondern eigentlich jede Methode, die eine weitere Methode aufruft.
@kleines_eichhoernchen:
nicht zu penibel sein Das sehe ich auch so.
@Golo Roden: Stino == Stinknormal 😉
R
Was ich leider bei den Dokumentationsmöglichkeiten vermisse ist, dass man die Werte von Konstanten ausgeben lassen kann. In folgendem Code-Ausschnitt bräuchte ich bei 3 Überladungen in den Kommentaren die Werte von int.MinValue und int.MaxValue.
public static class ESNumber
{
static Random _random = new Random();
/// <summary>
/// Errechnet eine Zufallszahl.
/// Als Generator wird derjenige des statischen Typs <see cref="ESNumber" /> benutzt.
/// Die inklusive untere Grenze der Zufallszahl ist -2147483648. Die inklusive obere Grenze der Zufallszahl ist 2147483647.
/// </summary>
/// <returns>Die Zufallszahl.</returns>
public static int GetRandomNumber()
{
return GetRandomNumber(_random);
}
/// <summary>
/// Errechnet eine Zufallszahl.
/// Die inklusive untere Grenze der Zufallszahl ist -2147483648. Die inklusive obere Grenze der Zufallszahl ist 2147483647.
/// </summary>
/// <param name="newRandom">
/// True, wenn ein neuer, temporärer Generator benutzt werden soll.
/// False, wenn derjenige des statischen Typs <see cref="ESNumber" /> benutzt werden soll.
/// </param>
/// <returns>Die Zufallszahl.</returns>
public static int GetRandomNumber(bool newRandom)
{
return GetRandomNumber(
(newRandom ? new Random() : _random)
);
}
/// <summary>
/// Errechnet eine Zufallszahl.
/// </summary>
/// <param name="newRandom">
/// True, wenn ein neuer, temporärer Generator benutzt werden soll.
/// False, wenn derjenige des statischen Typs <see cref="ESNumber" /> benutzt werden soll.
/// </param>
/// <param name="minValue">Die inklusive untere Grenze der Zufallszahl.</param>
/// <param name="maxValue">Die inklusive obere Grenze der Zufallszahl.</param>
/// <returns>Die Zufallszahl.</returns>
public static int GetRandomNumber(bool newRandom, int minValue, int maxValue)
{
return GetRandomNumber(
(newRandom ? new Random() : _random),
minValue,
maxValue
);
}
/// <summary>
/// Errechnet eine Zufallszahl.
/// Die inklusive untere Grenze der Zufallszahl ist -2147483648. Die inklusive obere Grenze der Zufallszahl ist 2147483647.
/// </summary>
/// <param name="random">Der Generator.</param>
/// <returns>Die Zufallszahl.</returns>
public static int GetRandomNumber(Random random)
{
return GetRandomNumber(random, int.MinValue, int.MaxValue - 1);
}
/// <summary>
/// Errechnet eine Zufallszahl.
/// Als Generator wird derjenige des statischen Typs <see cref="ESNumber" /> benutzt.
/// </summary>
/// <param name="minValue">Die inklusive untere Grenze der Zufallszahl.</param>
/// <param name="maxValue">Die inklusive obere Grenze der Zufallszahl.</param>
/// <returns>Die Zufallszahl.</returns>
public static int GetRandomNumber(int minValue, int maxValue)
{
return GetRandomNumber(_random, minValue, maxValue);
}
/// <summary>
/// Errechnet eine Zufallszahl.
/// </summary>
/// <param name="random">Der Generator.</param>
/// <param name="minValue">Die inklusive untere Grenze der Zufallszahl.</param>
/// <param name="maxValue">Die inklusive obere Grenze der Zufallszahl.</param>
/// <returns>Die Zufallszahl.</returns>
public static int GetRandomNumber(Random random, int minValue, int maxValue)
{
return random.Next(minValue, maxValue + 1);
}
}
Hallo retnug,
wieso brauchst du die Werte von int.MinValue und int.MaxValue? Schreib doch, dass das der Wert zwischen Int32.MinValue und Int32.MaxValue liegen muss. Wer die Werte dann nicht parat hat (eigentlich sollte man die parat haben) muss halt nachschlagen.
R
Naja, ich finde nicht gerade, dass ein Entwickler die Werte von int.MinValue und int.MaxValue unbedingt parat hat (auswendig kennt?). Und selbst wenn, ich finde es schade, dass die XML-Dokumentationskommentare nicht damit umgehen können.
Dann mach doch einen Link rein ins see also.
Dann kann er in der (von Sandcastle generierten) doku drauf clicken und sieht den Wert
Mein Stackoverflow Profil
Skype Name : Boas.Enkler (bitte einen hinweis in der Kontaktanfrage damit ich euch vom Spam unterscheiden kann)