Selecting overloaded methods to document

Topics: General Questions
Aug 26, 2008 at 1:42 PM
I'm new to DocProject and Sandcastle, so I may be posting this at the wrong place.  I'm in the process of converting our documentation from NDoc to Sandcastle.  For our documentation suite, we only document the public methods and constructors, nothing protected or private.  My initial pass at doing this with DocProject was to create a filter that excludes everything that is protected, internal, or private.  When I applied that filter, I received some unexpected results.

For instance, if I have the following constructors defined:
public SubError(int errorCode)
public SubError(int errorCode, string errorText)
protected SubError(int errorCode, string errorText, ObjParameter[] parameters)

All of these constructors were disabled. I tried to manually enable documentation on the public methods only.  As soon as I check one, all are checked.  If uncheck one, all are unchecked.

Is there something I'm doing wrong, an issue with DocProject, a limitation of DocProject, or a limitation in Sandcastle?

Thanks for your help
Aug 26, 2008 at 2:03 PM
Edited Aug 26, 2008 at 2:06 PM
Hi Tim,

Have you tried setting the Build | Documentation scope property to PublicOnly (the default value)?

If that setting is excluding too much then you can use a value of Complete instead and add one or more dynamic filters, as described below.

Applying a filter immediately does the same thing as unchecking nodes in Topic Explorer.  Unchecking nodes translates directly to the Sandcastle API filter, located in your project's Help\Presentation\Style\Configuration\MRefBuilder.config file.  A limitation of the API filter is that it only matches methods by name and not by their parameters, which means that when you exclude one overload you automatically exclude them all.

A work-around is to use DocProject's dynamic filter capability.  Set up the filter that you want and instead of applying it click the Save button.  Now move to the Saved Filters tab and you should see your filter in the list.  Make sure the Build column is checked and the filter will be applied automatically each time that you build help.  Also uncheck the Include column so that matching topics are excluded.  Click OK on the dialog to commit your changes (unless of course you're using the Topic Filters tool window).  Then click the Save All button in Visual Studio and the Help\Settings\dynamicFilters.xml file will be created.

Please let me know if there's any problem with either of my recommended approaches.

- Dave
Aug 26, 2008 at 5:53 PM
Hi Dave

I have the "Documentation scope" set to "PublicOnly".  Originally, I thought this would limit the build to the public members.  However, I noticed that protected entries were also appearing in the output.  That is when I started experimenting with the filters.

Creating the dynamic filter has solved about 99% of my problem.  I created a dynamic filter that excluded all private, protected, protected internal, and internal items.  I then left the documentation of all items turned on within the static filter.  I then built the documentation set.  None of my private, protected, protected internal, or internal items appeared in the documentation.  However, the inhereted protected members from the .NET Framework are still appearing.  For instance, the protected methods Finalize and MemberwiseClone from Object are still appearing in the documentation.

Can you suggest a way to exclude these as well?  I would like the inherited public methods to still appear.

Thanks again for your help.
Aug 26, 2008 at 6:28 PM
Hi Tim,

Maybe I should rename PublicOnly then, although technically protected members are public too in the sense that they are visible to types outside of the assembly in which they are defined.

As for inherited members showing, try using the inheritance filter.  On the Saved Filters tab, click the green plus sign and you should see it in the Available list.  You can configure it to match by prefixes, so if you don't want all inheritance information to be filtered out then add a prefix like System.Object and see if that does what you want.

- Dave