Code comment inheritence/pointers?

Topics: Developer Forum, User Forum
Nov 7, 2007 at 7:59 AM
Does anyone know if code comment inheritence (or pointers) is supported in Sandcastle? For instance, in Document! X, a member can be decorated like this (using the 'commentsfrom' tag) so as to automatically inject the code comments from an extended interface or base class.

public class MyImplementor : ICustomInterface
{
/// <commentsfrom cref="ICustomInterface.DoSomething" />
public bool DoSomething(int x)
{
return true;
}
}
Coordinator
Nov 7, 2007 at 4:11 PM
Sandcastle doesn't support that tag. You could implement a SHFB plug-in that scans the comments files and replaces that element with the proper documentation. I've got an idea for one that merges common documentation elements if they appear in multiple comments files. I'll add a note to see if it can support this too.

Eric
Nov 7, 2007 at 7:53 PM
Thanks a lot. Great work.

There's one more feature (this time from NDoc) that would be nice to have:

"Note: As of release 1.3, the MSDN and VS.NET documenters will only create a link on the first
occurrence of each unique cref specified within a documentation section; further <see> tags will
just be highlighted."

..from the doc found here: http://dynicity.com/Products/XMLDocComments.aspx

Thanks again.
Coordinator
Nov 7, 2007 at 8:08 PM
That would require a change to the actual Sandcastle transformations. I'm not sure how much work that would require or how to go about doing that. You might ask in the MSDN Documentation forum.

Eric
Nov 7, 2007 at 11:26 PM
OK - will do. Thanks
Coordinator
Mar 1, 2008 at 2:31 AM
Update: This topic was brought up again in the Sandcastle project forum and I've created a tool that can generate inherited documentation via the use of <inheritdoc /> tags similar to NDoc2 and the JavaDoc tool. I'm going to try and get it out late this weekend and it will contain full details on how it works. It'll be integrated with SHFB but can be used standalone with other community tools and custom build scripts.

Eric