NDoc has an XML element inheritdoc which allows you to inherit documentation of a member from the parent class (or an implemented interface). However, Visual Studio (i.e. the C# compiler) does not understand this tag and complains about the documentation not being present or complete. So does StyleCop and some other tools. Is there an alternative approach? How do you go about keeping the docs complete, yet without duplicating the XML descriptions?
The @inheritdoc tag indicates that a symbol should inherit its documentation from its parent class. Any other tags that you include in the JSDoc comment will be ignored. This tag is provided for compatibility with Closure Compiler.
C# documentation comments use XML elements to define the structure of the output documentation. One consequence of this feature is that you can add any valid XML in your documentation comments. The C# compiler copies these elements into the output XML file.
I have a better answer: FiXml.
Cloning comments with GhostDoc is certainly working approach, but it has significant disadvantages, e.g.:
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:
<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 (broken links).
Finally, there is <inheritdoc>
tag in Sandcastle - it's definitely better to use it than to copy XML comments, but it has few disadvantages in comparison to FiXml:
.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.<see ... copy="true" />
.See Sandcastle's <inheritdoc>
description for further details.
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With