DRY XML 注释答案

【问题标题】：DRY XML commentsDRY XML 注释
【发布时间】：2017-01-18 09:43:56
【问题描述】：

在提供同一个方法的多个重载时，我经常不得不重复方法的描述，这违反了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 文档。

【问题讨论】：

虽然我明白你为什么将它们添加为标签，但这不是 C# 或 VB 特定的问题......也许是 .NET 代替？
@DanielShillcock：如果有的话，我完全可以使用 C# 或 VB 解决方案。 :-) 有些 .NET 语言根本不支持 XML cmets（例如，Boo）。
我相信您的问题没有答案。在撰写文档时，您会经常重复自己:(
我能想到的对您所做的唯一改进是使用 <see cref=""/> 标签引用另一种方法。对于许多文档工具，这将生成指向其他方法的链接。
没有解决方案，但长期以来一直建议 Roslyn：github.com/dotnet/roslyn/issues/67

标签： c# vb.net documentation xml-documentation

【解决方案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）在这方面并没有真正的帮助，它不知道你在做什么。编译时，您将无法在项目的智能感知中看到它。如果您创建另一个解决方案并引用您的库，那么您会看到它。

【讨论】：