Exclude namespace and all nested namespaces

Topics: User Forum
Jan 26, 2015 at 9:03 AM

I need to document a handful of classes spread over about 20 DLLs and 100s of namespaces (all starting nested from one root namespace). New namespaces are added all the time, and I need those to be automatically excluded from the documentation.

Is there a way to say that I want to exclude the namespace "X", including all nested namespaces? And only document classes in namespaces "X.Y.Z1" and "X.Y.Z2", etc..

Using the "Visibility" properties does not appear to work as new namespaces will default to included.

Jan 26, 2015 at 5:02 PM
The API Filter accessed via the Visibility category is the way to exclude unwanted namespaces and types. However, how much you exclude from a particular namespace governs the type of filter generated. Exclude enough types (more than half) and it excludes the namespace and marks the specific types for inclusion. Only exclude a few (less than half) and it marks the namespace for inclusion with entries to exclude the few unwanted types. It's done that way for efficiency and will work well for the majority of cases. However, a side effect you can run into is the case noted where new types are included or excluded by default which may not be the behavior you want.

In this case, one option would be to mark all unwanted types, or at least new ones, with an <exclude /> tag in their XML comments. Such classes are automatically added to the project API filter at build time for exclusion. Other than that, all you can do is adjust the filter as necessary when you produce a new help file. If it's a big enough issue, you could write a plug-in to override the default API filter and set the it based on your own criteria at build time.

Marked as answer by Oblomov on 1/27/2015 at 5:16 AM
Jan 27, 2015 at 12:16 PM
Hi Eric,

Thanks for the response (and the excellent tool as well!).

I managed to get this to work using the 'XPath Reflection File Filter', all the namespaces I want to document have a fixed substring, so it is actually a reasonably clean solution.

Marked as answer by Oblomov on 1/27/2015 at 5:16 AM
Feb 23, 2015 at 3:44 PM
Edited Feb 26, 2015 at 7:23 PM
Thank you for the inspiration, Oblomov! For others' reference, I used the "XPath Reflection File Filter" to implement a namespace wildcard-whitelist approach. To do so I added to the plugin's configuration one XPath expression like the following, with another or for each desired namespace prefix:
/reflection/apis/api[not(contains(@id,":SOME_NAMESPACE_PREFIX_FOR_INCLUSION.") or contains(@id,":ANOTHER_NAMESPACE_PREFIX_FOR_INCLUSION."))]