DRY XML comments

Question

When providing multiple overloads of the same method, I often have to repeat the description of the method, which violates DRY and increases maintenance cost:

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

This problem gets worse if multiple parameters with the same purpose are repeated ("hasBar" is given as an example).

One "workaround" I found is to "reference" the other documentation:

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

Obviously, that's less convenient for the user of the library.

Is there some built-in mechanism (or smart strategy) that I can use to avoid duplication and make life easy for the users of my methods? I am mainly concerned about IntelliSense, not generated HTML documentation.

Answer 1

There is actually a solution using XML tag. You actually build your documentation in a XML file and then link your method to this XML file. Here is a small example I made up.

Solution here is in VB.NET, but I guess it won't be really difficult to convert it to C#...

First, you need a standard library 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

So the doc for the class and the first method are "standard". For the SecondMethod, I provide a XML link.

So next you need to create a XML file, here called DocFile.XML where you will put the documentation for your methods:

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

And when you compile it together and create the documentation (here I used SandCastle), it produces the following:

And for each method:

and

TLDR

• It is possible to create the documentation once in a XML file and link the methods to this documentation.
• You can link many methods to one definition
• Case is sensitive
• Visual Studio (here I used VS 2010 Express) is not really helpfull on this one, it has no idea of what you're doing. When you compile, you will not be able to see it in the intellisense of your project. If you create another solution and reference your library then you will see it.