Ways to synchronize interface and implementation comments in C#

by

You can do this quite easily using the Microsoft Sandcastle (or NDoc) inheritdoc tag. It’s not officially supported by the specification, but custom tags are perfectly acceptable, and indeed Microsoft chose to copy this (and one or two other tags) from NDoc when they created Sandcastle.

/// <inheritdoc/>
/// <remarks>
/// You can still specify all the normal XML tags here, and they will
/// overwrite inherited ones accordingly.
/// </remarks>
public void MethodImplementingInterfaceMethod(string foo, int bar)
{
    //
}

Here is the help page from the Sandcastle Help File Builder GUI, which describes its usage in full.

(Of course, this isn’t specifically “synchronisation”, as your question mentions, but it would seem to be exactly what you’re looking for nonetheless.)

As a note, this sounds like a perfectly fair idea to me, though I’ve observed that some people think you should always respecify comments in derived and implemented classes. (I’ve actually done it myself in documenting one of my libraries and I haven’t see any problems whatsoever.) There’s almost always no reason for the comments to differ at all, so why not just inherit and do it the easy way?

Edit: Regarding your update, Sandcastle can also take care of that for you. Sandcastle can output a modified version of the actual XML file it uses for input, which means you can distribute this modified version along with your library DLL instead of the one built directly by Visual Studio, which means you have the comments in intellisense as well as the documentation file (CHM, whatever).

More Related Contents:

  1. How to reference generic classes and methods in xml documentation
  2. How to add a line break in C# .NET documentation
  3. How can Xml Documentation for Web Api include documentation from beyond the main project?
  4. Programmatically get Summary comments at runtime
  5. Where are CLR-defined methods like [delegate].BeginInvoke documented? [closed]
  6. How do you get XML comments to appear in a different project (dll)?
  7. Parse DateTime with time zone of form PST/CEST/UTC/etc
  8. Why does .NET add an additional slash to the already existent slashes in a path?
  9. How to enable design support in a custom control?
  10. two different DLL with same namespace
  11. How can a Word document be created in C#? [closed]
  12. How to detect if a property exists on an ExpandoObject?
  13. Not able to cast string to int. Error msg: Input string was not in a correct format
  14. Observable Stack and Queue
  15. Having the output of a console application in Visual Studio instead of the console
  16. Programmatic way to get all the available languages (in satellite assemblies)
  17. ASP.NET MVC Routing – add .html extension to routes
  18. Webdriver How to wait until the element is clickable in webdriver C#
  19. How to TryParse for Enum value?
  20. Add multiple images in the email body (inline)using c# windows application
  21. Comparing floating point values
  22. Update requires a valid UpdateCommand when passed DataRow collection with modified rows
  23. Global setting for AsNoTracking()?
  24. Auto-Implemented Properties c#
  25. Extract only right most n letters from a string
  26. C# Get property value without creating instance?
  27. How to find out the Encoding of a File? C#
  28. EF models. Navigation properties can only participate in a single relationship
  29. What’s the difference between casting an int to a string and the ToString() method in C#
  30. Reloading an image in wpf

Leave a Comment