CODEWITHSUNDEEP
c#.netvisual-studiodocumentationxml-documentation
ekolis
ekolis

Reputation: 6776

How to sync XML comments between C# parent classes/interfaces and child classes

In Java, if I have a Javadoc on a parent class or interface, then the Javadoc appears in the context of a child class or interface in most IDEs when I hover over the child class name. However, this doesn't seem to be true in Visual Studio with C#'s XML comments. Is there any way to automatically sync the XML comments between parent and child classes, so I don't have to copy/paste them and sync them manually?

Upvotes: 2

Views: 1438

Answers (3)

K Johnson
K Johnson

Reputation: 488

I built a tool to post-process the XML documentation files to add support for the <inheritdoc/> tag.

While it doesn't help with Intellisense in source code, it does allow the modified XML documentation files to be included in a NuGet package and therefore works with Intellisense in referenced NuGet packages.

It's at www.inheritdoc.io (free version available).

Upvotes: 2

Sam Harwell
Sam Harwell

Reputation: 99859

If you are creating a library that other projects will use, then you have a great option available with Sandcastle Help File Builder's (SHFB) <inheritdoc> tag. While Visual Studio doesn't natively understand this tag, SHFB provides an IntelliSense Component that reads the XML documentation file produced by your project, and writes out a new XML documentation file with all <inheritdoc> tags replaced by the inherited documentation. This is exactly the process we use for shipping the XML documentation for the openstack.net SDK on NuGet:

  1. Create XML documentation during the build.

    enter image description here

  2. Include the IntelliSense Component in our SHFB project.

    Configure IntelliSense Component

  3. Create a .nuspec file (NuGet Package Specification) that explicitly references the XML documentation created by the IntelliSense Component instead of the documentation created by the C# compiler.

While inside Visual Studio, it's also beneficial to be able to see the documentation for base classes. I use the Inheritance Margin extension to jump from an overriding or implementing method to the base class or interface where it is fully documented.

Upvotes: 3

dcastro
dcastro

Reputation: 68640

Visual Studio doesn't provide this out of the box. There's no way to keep them in sync, or to make derived types inherit XML documentation.

But if you have Resharper installed, it will give you the option to copy XML comments from the base type to the derived type.

enter image description here

Upvotes: 2

Related Questions