Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

Ways to synchronize interface and implementation comments in C# [closed]

Are there automatic ways to sync comments between an interface and its implementation? I'm currently documenting them both and wouldn't like to manually keep them in sync.

UPDATE:

Consider this code:

interface IFoo{     /// <summary>     /// Commenting DoThis method     /// </summary>     void DoThis(); } class Foo : IFoo {     public void DoThis(); } 

When I create class like this:

IFoo foo=new Foo(); foo.DoThis();//comments are shown in intellisense 

Here comments are not shown:

Foo foo=new Foo(); foo.DoThis();//comments are not shown in intellisense 

The <inheritDoc/> tag will perfectly generate the documentation in Sand Castle, but it doesn't work in intellisense tooltips.

Please share your ideas.

Thanks.

like image 385
Valentin V Avatar asked May 05 '09 09:05

Valentin V


1 Answers

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).

like image 106
Noldorin Avatar answered Oct 01 '22 01:10

Noldorin