Documentation only for specific APIs

Topics: Developer Forum
Jun 28, 2012 at 1:00 AM

Hi,

I would like to document only specific APIs in the assembly. I could see that we can achieve this using APIFilter feature in SandCastle Help File Builde. Since assembly has huge set of APIs and frequently updated, it may not be maintainable using APIFilter.

I would like to define some custom tag and add it on top of the API (as similar to the below example) so that Sandcastle would document only the API with the custom tag.

 Example:

/// <summary>
/// Returns X.
/// </summary>
/// <IncludeInDocumentation />
public class ABC
{
     public ABC()
     {
     }

     /// <summary>
     /// Returns X.
     /// </summary>
     /// <IncludeInDocumentation />
     public int GetX()
     {
        return x;
     }


     /// <summary>
     /// Returns XY.
     /// </summary>
     public int GetXY()
     {
        return Y;
     }
}

In the above example, output chm should only have documentation for type "ABC" and method "GetX()" which are decorated with custom tag <IncludeInDocumentation />, not for method "GetXY()".

Adding <exclude /> would also help us but due to project constraint, we cannot add <exclude/> for all the unwanted APIs.

Please let me know, if there is any built in feature to achieve this or any pre-built custom plugin available?

Could you please provide your recommendation?

Coordinator
Jun 28, 2012 at 8:31 PM

There isn't a way to do what you want currently nor are there any plug-ins that I'm aware of that would do it.  The best approach would be to create a plug-in that scans the XML comments in the working folder at build time and inserts an <exclude /> tag into any member comments that do not include your custom <IncludeInDocumentation> tag.  SHFB would then add all of the excluded members to the API filter automatically.

Eric