XML Documentation Comments with Interfaces and implementing class(es)

Question

I am documenting an assembly using XML Documentation Comments, from which a chm file will be created using Sandcastle.

My assembly contains various interfaces, each of which is implemented by one class (in my scenario these are WCF services).

I have added documentation to the interfaces, is there any way for me to automatically document the relevant methods on the implementing classes?

Answer 1

A tool such as GhostDoc can generate the documentation on the implementing classes, when you use it's keyboard shortcut. That is not entirely automatic, but could help prevent too much copy pasting.

Perhaps it could be automized with a script.

Answer 2

There seems to not be any support for such autodocumentation in Sandcastle. The Sandcastle Help File Builder though implements a custom inheritdoc tag.

From the SHFB site:

Support is included for the <inheritdoc /> tag which allows you to inherit documentation from base types/members. This is implemented via a standalone tool so it can also be used by other third-party tools and build scripts. This tool provides features beyond those found in the build component supplied with Sandcastle.

Second Update: according to this workitem, the Sandcastle "support" for inheritdoc is through the SHFB tool. Bottom line I suppose is, SHFB solves your problem.

Answer 3

AtomineerUtils will auto-generate comments for you, and it picks up existing documentation from overloads and overridden base class, saving you loads of hassle in duplicating the information where it's needed.

http://www.atomineer.com/AtomineerUtils.html

Answer 4

I have a better answer: FiXml.

Cloning comments with GhostDoc \ AtomineerUtils is certainly working approach, but it has significant disadvantages, e.g.:

• When the original comment is changed (which frequently happens during development), its clone is not.
• You're producing huge amount of duplicates. If you're using any source code analysis tools (e.g. Duplicate Finder in Team City), it will find mainly your comments.

As it was mentioned, there is <inheritdoc> tag in Sandcastle, but it has few disadvantages in comparison to FiXml:

• Sandcastle produces compiled HTML help files - it doesn't modify .xml files containing extracted XML comments. But these files are used by many tools, including .NET Reflector and class browser \ IntelliSense in Visual Studio .NET. So if you use just Sandcastle, you won't see inherited documentation there.
• Sandcastle's implementation is less powerful. E.g. the is no <see ... copy="true" />.

See Sandcastle's <inheritdoc> description for further details.

Short description of FiXml: it is a post-processor of XML documentation produced by C# \ Visual Basic .Net. It is implemented as MSBuild task, so it's quite easy to integrate it to any project. It addresses few annoying cases related to writing XML documentation in these languages:

• No support for inheriting the documentation from base class or interface. I.e. a documentation for any overridden member should be written from scratch, although normally it’s quite desirable to inherit at least the part of it.
• No support for insertion of commonly used documentation templates, such as “This type is singleton - use its <see cref="Instance" /> property to get the only instance of it.”, or even “Initializes a new instance of <CurrentType> class.”

To solve mentioned issues, the following additional XML tags are provided:

• <inheritdoc />, <inherited /> tags
• <see cref="..." copy="..." /> attribute in <see/> tag.

Here is its web page and download page.