Auto referencing external documentation

Jan 22, 2009 at 9:49 AM
When you develop software that implement interfaces/overrides methods a lot of the time there is nothing more to say about the method than the original documentation.

What I would like is a way of using something like <include> and have it figure out where to copy the documentation from e.g.

public interface IFred
{
     /// <summary>
     /// This is the documentation for method.
     /// <summary>
     void Method();
}

public class FredImpl
{
     /// <include cref="IFred" section="all" />
     void Method();
}

The tricky bit of this I think is when IFred is in another assembly and/or project.

This will cut down on the ~2000 documentation failings I currently have :-)
Jan 22, 2009 at 10:06 AM
Hi,

You case use <include file="{relative path}" path="{xpath}" /> and the C# compiler will pull information from the specified XML file and include it into the XML documentation file that it creates.  This has nothing to do with Sandcastle.

http://msdn.microsoft.com/en-us/library/9h8dy30z.aspx

The MSDN documentation appears to be messed up.  Here's another source of information about the include tag, with some examples:

http://social.msdn.microsoft.com/forums/en-US/devdocs/thread/9425dec9-55fd-40aa-be93-e6933f802322/ 

- Dave
Jan 22, 2009 at 10:11 AM
Hi,

Also of possible interest, Sandcastle supports <inheritdoc/>.

- Dave
Editor
Jan 22, 2009 at 7:31 PM
As Dave noted, <inheritdoc /> is probably what you want.  The implementation supplied by Sandcastle doesn't support any attributes to filter the inherited comments.  The GenerateInheritedDocs tool supplied with the Sandcastle Help File Builder does support filtering.  It's built into the help file builder by default.  If you are using another community tool or your own build scripts, you can get it by downloading the Standalone Build Components from the project site.

Eric