DRY XML评论

Question

当提供相同方法的多个重载时,我经常不得不重复该方法的描述,这违反了DRY并增加了维护成本:

/// <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）时，它会生成以下内容：

对于每种方法：

和

总长DR

• 可以在 XML 文件中创建一次文档并将方法链接到该文档。
• 您可以将多种方法链接到一个定义
• 大小写敏感
• Visual Studio（这里我使用的是 VS 2010 Express）对此并没有多大帮助，它不知道你在做什么。当你编译时，你将无法在项目的智能感知中看到它。如果您创建另一个解决方案并引用您的库，那么您将看到它。