 |
OpenKeyWord
Version: 426, Datum:
|
|
OpenKeyWord
Version: 426, Datum:
|
Für die Dokumentation des Quelltextes wird [Doxygen] verwendet. Nähere Informationen zu Doxygen finden Sie unter (http://www.doxygen.org) Vor diesem Hintergrund müssen für die Dokumentationen des Quelltextes die Regelungen von Doxygen Beachtung finden.
Um bei verschiedenen Programmierern einen einheitlichen Programmierstil zu gewährleisten, wird ein zweites Werkzeug im Projekt OKW genutzt: [StyleCop]. Weitere Informationen zu [StyleCop] finden Sie unter (https://stylecop.codeplex.com/).
Damit beide Werkzeuge ohne Fehler oder Warnungen den Quelltext akzeptieren sind einige Punkte in der Kodierung und Dokumentation einzuhalten
Die Zuständigkeiten beider Werkzeuge sind grundsätzlich wie folgt geregelt:
Sofern sich die Zuständigkeiten beider Werkzeuge überschneiden (Regelkonkurrenz), gelten folgende Regeln. Dies sind die Grundregeln der Dokumentation:
///.Beispiel für die vier Vorgaben von oben.
/// Name des Kunden
/// 2. Zeile der Dokumentation sName
string sName
/// Vorname des Kunden
/// 2. Zeile der Dokumentation sVorname
string sVorname
StyleCop definiert die Regel SA1644: DocumentationHeadersMustNotContainBlankLines, die mit der Dokumentationskonventionen von DoxyGen kollidiert. Regel SA1644: DocumentationHeadersMustNotContainBlankLines verbietet das Einfügen von Leerzeilen in der Dokumentation. DoxyGen dagegen benötigt für die Trennung von Absätzen ganau diese Leerzeilen.
Die Kurzbeschreibung und die weitergehenden Datailbeschreibung eines Elementes werden mit einer Leerzeile (oder mit einem anderen Befehl) abgetrennt werden, sonst trennt Doxygen die beiden Beschreibungen nicht von einander und die Detailbeschreibung wird in der Kurzbeschreibung dargestellt.
Beispiel:
/// \~german
/// <summary>
/// Das ist die Kurzbeschreibung, in Doxygen brief-description bezeichnet .
///
/// Nach der Leerzeile erfolgt die Detailbeschreibung des Elementes, hier eine Methode.
/// \~english
/// <summary>
/// This is the brief or short description.
///
/// After a blank line the detail description starts for the element, in this case for a method.
/// \~
/// \author Zoltan Hrabovszki
/// \date 2014.01.14
public void MeineMethode( )
{
. . .
return;
}
Beispiel: für die Dokumentaion einer Methode. (CurrentObject::CallMethod(string,string))
/// \~german
/// <summary>
/// Ruft eine Methode des aktuellen Objektes via _late bound function call_ auf.
///
/// Die aufgerufene Methode hat die Signatur:
/// | Parameter/Return | Type |
/// | :----------------|:------|
/// | Parameter | keine |
/// | Rückgabewert | kein |
/// </summary>
/// <param name='fpsMethod'>Name der Methode, die aufgerufen werden soll.</param>
///
/// \~english
/// <summary>
/// Calls a method of the current object with "late bound function call".
///
/// The called method has the signature:
/// | Parameter/Return | Type |
/// | :----------------|:------|
/// | Parameter | none |
/// | Return | none |
/// </summary>
/// <param name='fpsMethod'>name of method to be called</param>
///
/// \~
/// \author Zoltan Hrabovszki
/// \date 2014.01.14
public void CallMethod(string fpsMethod)
{
this.Log.LogFunctionStartDebug("CallMethod", "string fpsMethod", fpsMethod);
try
{
Type myTypeObject = this.cvoObject.GetType();
MethodInfo myMethodInfo = myTypeObject.GetMethod(fpsMethod,
BindingFlags.Public | BindingFlags.Instance,
null,
new Type[] {},
null);
// Existiert die Methode des Objektes?
if (myMethodInfo == null)
{
// Nein: -> Mit einem OKWFrameObjectMethodNotFoundException aussteigen...
string errorText = this.LM.GetMessage("CallMethod", "MethodNotDefined", fpsMethod);
throw new OKWFrameObjectMethodNotFoundException(errorText);
}
else
{
// Ja, Methode via Invoke aufrufen
myMethodInfo.Invoke(this.cvoObject, null);
}
}
finally
{
this.Log.LogFunctionEndDebug();
}
return;
}
Die Dokumentation ist für mehrere Sprachen ausgelegt, bzw. nutzt die Möglichkeiten von Doxygen um die Dokumentation für mehrere Sprachen zu erstellen. Dazu werden im Kommentarblock die einzelnen Sprachabschnitte jeweils mit einen Befehl von einander getrennt. In OKW werden die Sprachen deutsch und englisch gepflegt, die mit den Befehlen:
\~german
\~english
eingeleitet werden.
Neben den Sprachabschnitten gibt es noch einen sprachunabhängigen oder sprachübergreifenden Abschnitt, dieser wird mit
\~
eingeleitet. Hier werden Angaben gemacht, die für alle Sprachen einheitlich gelten, z.B. Author des Quelltextes oder Erstellungsdatum.
Die Kurzbeschreibung ist der erste Abschnitt in der Dokumentation. Dieser kann mit \brief eingeleitet werden. Das Ende der Kurzbeschreibung wird entweder durch eine Leerzeile oder durch einen anderen DoxyGen Befehl markiert. Siehe dazu das Beispiel im Kapitel Doxygen/StyleCop Zuständigkeitsüberschneidung .
Die Übergabeparameter einer Methode werden jeweils mit dem param-Tag beschrieben. Diese haben folgende Form:
<param name='ParameterName'>Beschreibung des Parameters</param>
Das Attribut name muss jeweils mit dem Namen des Parameters in der Deklarationszeile der Methode, die beschrieben werden soll, korrespondieren.
Als Beispiel folgender Dokumentationsabschnitt:
/// <param name='Paramter_1'>Hier wird der 1. Parameter beschrieben.</param>
/// <param name='Paramter_2'>Hier wird der 2. Parameter beschrieben.</param>
///
public void CallMethod(string Parameter_1, string Parameter_2)
name der Bezeichner des Parameters falsch geschrieben sein, löst Doxygen eine Warnung aus und die Beschreibung des Parameters fehlt in der generierten DoxyGen-Ausgabe..Mit
<return>Beschreibung des Rückgabewertes.</return>
wird der Rückgabewert einer Methode Beschrieben.
1.8.10