DRY XML комментарии

Question

При предоставлении нескольких перегруженных одного и того же метода, мне часто приходится повторять описание метода, который нарушает СУХОЙ и увеличивает стоимость обслуживания:

/// <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) 
{ 
    ... 
} 

Эта проблема становится хуже, если несколько параметров с то же назначение повторяется (в качестве примера приводится «hasBar»).

Один «обходной путь» Я нашел это «ссылка» другая документация:

/// <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) 
{ 
    ... 
} 

Очевидно, что менее удобно для пользователя библиотеки.

Есть ли встроенный механизм (или умная стратегия), который я могу использовать, чтобы избежать дублирования и сделать жизнь легкой для пользователей моих методов? Я в основном обеспокоен IntelliSense, а не созданной HTML-документацией.

Answer 1

Фактически существует решение с использованием тега XML. Фактически вы создаете свою документацию в XML-файле, а затем связываете свой метод с этим XML-файлом. Вот небольшой пример, который я составил.

Решение здесь в VB.NET, но я предполагаю, что это не будет очень трудно преобразовать его в C# ...

Во-первых, вам необходимо стандартное определение библиотеки:

''' <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 

Таким образом, документ для класса и первый метод являются «стандартными». Для SecondMethod я предоставляю ссылку XML.

Так что в следующий вам нужно создать XML-файл, здесь под названием DocFile.XML, где вы поставите документацию для методов:

<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> 

И когда вы собираете вместе и создавать документацию (здесь я SandCastle), он производит следующие действия:

И для каждого метода:

и

TLDR

• Можно создать документацию раз в файле XML и связать методы этой документации.
• Вы можете связать множество методов определения одного
• Корпуса чувствительного
• Visual Studio (здесь я использовал VS 2010 Express) не очень полезно на этом, он не имеет ни малейшего представления о том, что вы делаете. Когда вы компилируете, вы не сможете увидеть его в intellisense вашего проекта. Если вы создадите другое решение и обратитесь к своей библиотеке, вы увидите его.