DRY XML-Kommentare

Question

Wenn mehrere Überlastungen der gleichen Methode bereitstellt, ich habe oft die Beschreibung des Verfahrens zu wiederholen, die DRY verletzt und erhöht die Wartungskosten:

/// <summary> 
/// Frobnicates all foos read from the given reader. Frobnication is a 
/// process where ...[lots of text]... 
/// </summary> 
/// <param name="hasBar">[Description of hasBar]</param> 
void FrobnicateFoo(TextReader reader, bool hasBar) 
{ 
    ... 
} 

/// <summary> 
/// Frobnicates all foos read from the given file. Frobnication is a 
/// process where ...[same lots of text]... 
/// </summary> 
/// <param name="hasBar">[Same description of hasBar]</param> 
void FrobnicateFoo(String path, bool hasBar) 
{ 
    ... 
} 

Dieses Problem wird noch schlimmer, wenn mehrere Parameter mit der Der gleiche Zweck wird wiederholt ("hasBar" wird als Beispiel angegeben).

One „Abhilfe“ Ich fand auf „Referenz“ die andere Dokumentation:

/// <summary> 
/// Frobnicates all foos read from the given reader. Frobnication is a 
/// process where ...[lots of text]... 
/// </summary> 
/// <param name="hasBar">[Description of hasBar]</param> 
void FrobnicateFoo(TextReader reader, bool hasBar) 
{ 
    ... 
} 

/// <summary> 
/// Convenience method which opens the file with a UTF-8 encoding and then 
/// frobnicates all foos, see FrobnicateFoo(TextReader). 
/// </summary> 
void FrobnicateFoo(String path, bool hasBar) 
{ 
    ... 
} 

Offensichtlich, das ist weniger bequem für den Benutzer der Bibliothek.

Gibt es einen eingebauten Mechanismus (oder intelligente Strategie), den ich verwenden kann, um Doppelarbeit zu vermeiden und machen das Leben einfach für die Benutzer meiner Methoden? Ich bin hauptsächlich besorgt über IntelliSense, nicht generierte HTML-Dokumentation.

Answer 1

Es gibt tatsächlich eine Lösung mit XML-Tag. Sie erstellen Ihre Dokumentation in einer XML-Datei und verknüpfen dann Ihre Methode mit dieser XML-Datei. Hier ist ein kleines Beispiel, das ich erfunden habe.

Lösung ist hier in VB.NET, aber ich denke, es wird nicht wirklich schwer zu wandeln es in C# ...

Zuerst müssen Sie eine Standard-Bibliothek Definition:

''' <summary> 
''' This is my First class 
''' </summary> 
''' <remarks></remarks> 
Public Class FirstClass 
    ''' <summary> 
    ''' This is my first method 
    ''' </summary> 
    ''' <param name="A">A</param> 
    ''' <returns>True</returns> 
    ''' <remarks></remarks> 
    Public Function FirstMethod(A As Integer) As Boolean 
     Return True 
    End Function 

    ''' <include file="DocFile.xml" path="Doc/member[@name='SecondMethod']/*" /> 
    Public Function SecondMethod(A As Integer) As String 
     Return "Hello" 
    End Function 

    ''' <include file="DocFile.xml" path="Doc/member[@name='SecondMethod']/*" /> 
    Public Function SecondMethod(A As Integer, B As String) As String 
     Return "Hello" 
    End Function 

    ''' <include file="DocFile.xml" path="Doc/member[@name='SecondMethod']/*" /> 
    Public Function SecondMethod(A As Integer, B As String, C As Boolean) As String 
     Return "Hello" 
    End Function 

End Class 

Das Dokument für die Klasse und die erste Methode sind also "Standard". Für die SecondMethod stelle ich eine XML-Verbindung zur Verfügung.

So nächstes müssen Sie eine XML-Datei erstellen, hier genannt DocFile.XML, wo Sie die Dokumentation für Ihre Methoden setzen wird:

<Doc> 
    <member name="SecondMethod"> 
    <summary> 
     This is my second method 
    </summary> 
    <param name="A">a</param> 
    <param name="B">b</param> 
    <param name="C">c</param> 
    <returns>A string containing "Hello"</returns> 
    <remarks></remarks> 
    </member> 
</Doc> 

Und wenn man es zusammen kompilieren und die Dokumentation erstellen (hier habe ich SandCastle), erzeugt es die folgenden:

Und für jede Methode:

und

TLDR

• Es ist möglich, die Dokumentation einmal in einer XML-Datei und verknüpfen die Methoden zur Dokumentation zu erstellen.
• Sie können viele Methoden, um eine Definition
• Case sensitive
• Visual Studio Link (hier verwendete ich VS 2010 Express) auf dieser einen nicht wirklich hilfsbereit, es hat keine Ahnung von dem, was du tust. Wenn Sie kompilieren, können Sie es nicht im Intellisense Ihres Projekts sehen. Wenn Sie eine andere Lösung erstellen und auf Ihre Bibliothek verweisen, werden Sie sie sehen.