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.

Although I see why you've added them as tags, this is not a C# or VB specific question... Maybe .NET instead? — IronAces, Jan 18 '17 at 10:14
@DanielShillcock: I'm perfectly fine with C#- or VB-only solution, should there be any. :-) There are .NET languages which do not support XML comments at all (Boo, for example). — Heinzi, Jan 18 '17 at 10:24
I believe that there's no answer to your question. While composing docs, you're going to repeat yourself a lot :( — Matías Fidemraizer, Jan 18 '17 at 10:26
The only improvement over what you did that I can think of is referencing the other method withe the `` tag. Which will, for many documentation tools, generate a link to the other method. — Irwene, Jan 18 '17 at 10:34
No solution, but it's long been suggested for Roslyn: https://github.com/dotnet/roslyn/issues/67 — Lennart, Jan 18 '17 at 10:50
@Lennart I didn't know that there were an issue for this. BTW I was sure that Roslyn would be the best tool to improve documentation experience! — Matías Fidemraizer, Jan 18 '17 at 10:53

Martin Verjans · Answer 1 · 2017-03-13T09:10:53.500

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.

DRY XML comments

1 Answers1