5

I have a generic abstract base class that has some methods on it. Those methods have XML Comments on them as such:

/// <summary>
///     Controller for working with instances of {TModel}
/// </summary>
public abstract class BaseController<TModel> : ApiController
{
    /// <summary>
    ///     Creates a {TModel}.
    /// </summary>
    [HttpPost]
    public Task<TModel> Post([FromBody] TModel model)
    {
        ...
        return ...
    }
}

I would like to be able to implement it as such:

/// <summary>
///     Controller for working with instances of PersonModel
/// </summary>
public class PersonController : BaseController<PersonModel>
{
}

And have XML comments generated for PersonController that mimic the comments on the base class. That would allow something fancy like https://github.com/domaindrivendev/Swashbuckle to pick up my XML Comments and display them nicely for the PersonController.

Currently the comments come out as follows:

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>MyLibrary</name>
    </assembly>
    <members>
        <member name="T:MyLibrary.PersonController">
            <summary>
                Controller for working with instances of PersonModel
            </summary>
        </member>
        <member name="T:MyLibrary.BaseController`1">
            <summary>
                Controller for working with instances of {TModel}
            </summary>
        </member>
        <member name="M:MyLibrary.BaseController`1.Post(`0)">
            <summary>
                Creates a {TModel}.
            </summary>
        </member>
    </members>
</doc>

I would like it to also include a method documentation for the post method on PersonController, too:

...
<member name="M:MyLibrary.PersonController.Post(`0)">
    <summary>
        Creates a PersonModel.
    </summary>
</member>
...

At this point, I feel I've wasted too much time trying to figure out how to make it do what I want. Can any of you help me find a shortcut?

Jereme
  • 1,445
  • 1
  • 16
  • 32
  • 2
    Some tools (such as ReSharper or GhostDoc) can make comment generation or duplication easier. There is an extension to the xml tags supported by (among others) NDoc and Sandcastle so you can put `/// ` to easily inherit the comments from the base class or interface, but it's not universally supported. – christophano Apr 14 '15 at 21:33
  • How do those handle inheriting method comments from the base class when they do not exist in the derived class? The xml file msbuild generates doesn't have comments for those methods on the derived types. – Jereme Apr 14 '15 at 21:41
  • Short term your best bet is a tool like ReSharper (where you can pull comments up from a base class or interface), although I appreciate not everyone uses or likes it. Longer term, encouraging (and/or implementing) `` support in Swashbuckle would be great. – christophano Apr 14 '15 at 21:45
  • It looks like something like would work at the class level, but it still wouldn't result in documentation for the method post. I'll edit the question with the XML documentation example how it is now and what I would like it to be. – Jereme Apr 14 '15 at 21:58
  • Support for inheritdoc in Visual Studio is long overdue, in my opinion. – christophano Apr 14 '15 at 22:28

0 Answers0