Share via

Filtering APIs using Sandcastle

  • Article

 

API filters in Sandcastle is a very useful feature and allows namespaces, types, and members to be removed or shown in the reflection XML file, and ultimately in the compiled docs. They can be set up so that only certain topics are dropped, or so that a parent type has all children hidden with only specific ones shown. The API filter configuration can be found in ProductionTools\MRefBuilder.config file and is contained within an apiFilter element.

If no apiFilter element exists the default is to expose everything. This is the same as having an empty apiFilter element that is exposed such as

<apiFilter expose="true"></apiFilter>

Setting expose to false will hide everything, which is useful if you wish to expose only certain namespaces, types, or methods.

<apiFilter expose="false"></apiFilter>

Filter Inheritance

Filters inherit from their parent filter, with the exception of nested types which look to their parent type(s) before the namespace filter.

 

In the example below, only ThirdNamespace will be exposed. All other namespaces will be left out. Also, all types in ThirdNamespace and methods within those types will be shown. Types and methods in other namespaces will be left out.

 

<apiFilter expose="false">

    <namespace name="ThirdNamespace" expose="true"></namespace>

</apiFilter>

 

This filter shows everything except for ThirdNamespace and it types and members.

 

<apiFilter expose="true">

    <namespace name="ThirdNamespace" expose="false"></namespace>

</apiFilter>

 

If a filter is exposed within a non-exposed filter it will still be shown. The example below results in only the single method being exposed along with its declaring types. No other children of the declaring types are exposed. Without the filter for MyMethod, or with the filter set to false, everything will be hidden.

 

<apiFilter expose="false">

  <namespace name="MyNamespace" expose="false">

      <type name="MyClass" expose="false">

            <member name="MyMethod" expose="true" />

      </type>

  </namespace>

</apiFilter>

 

A filter to show all types within MyClass, but leave out MyMethod and MyMethod2 would look like this

<apiFilter expose="false">

  <namespace name="MyNamespace" expose="false">

      <type name="MyClass" expose="true">

            <member name="MyMethod" expose="false" />

            <member name="MyMethod2" expose="false" />

      </type>

  </namespace>

</apiFilter>

Nested Types

Nested types inherit from their parent type. If a type is nested within other nested types it will go through the parent types until it finds a filter.

In the examples below are filters for a class with contains a class called MyNestedNestedClass which is nested within MyNestedClass. MyNestedClass is nested with a class called MyClass.

MyNamespace
- MyClass
- MyNestedClass
-MyNestedNestedClass

This filter will hide everything except for MyNestedClass and its types. Since we set MyNestedNestedClass to be hidden it will not show up. MyClass is also hidden since MyNamespace is not exposed.

<apiFilter expose="false">

  <namespace name="MyNamespace" expose="false">

      <type name="MyNestedClass" expose="true"></type>

      <type name="MyNestedNestedClass" expose="false"></type>

  </namespace>

</apiFilter>

Here MyNestedNestedClass will also be shown since its declaring type (MyNestedClass) is shown.

<apiFilter expose="false">

  <namespace name="MyNamespace" expose="false">

      <type name="MyNestedClass" expose="true"></type>

  </namespace>

</apiFilter>

 

Exposing members within nested types works the same as with regular types. Using this filter only MyNestedMethod will be shown, leaving MyNestedNestedClass hidden, and all other members within MyNestedClass.

<apiFilter expose="false">

  <namespace name="MyNamespace" expose="false">

      <type name="MyNestedClass" expose="false">

            <member name="MyNestedMethod" expose="true" />

      </type>

  </namespace>

</apiFilter>

General Examples

The following example filters out three namespaces, and 11 types within the System namespace.

<apiFilter expose="true">

      <namespace name="System" expose="true">

      <type name="BrowsableAttribute" expose="false" />

      <type name="DefaultMemberAttribute" expose="false" />

      <type name="IntPtr" expose="false" />

      <type name="MulticastDelegate" expose="false" />

      <type name="NonScriptableAttribute" expose="false" />

      <type name="ParamArrayAttribute" expose="false" />

      <type name="RuntimeFieldHandle" expose="false" />

      <type name="RuntimeTypeHandle" expose="false" />

      <type name="UIntPtr" expose="false" />

      <type name="Void" expose="false" />

      </namespace>

      <namespace name="System.ComponentModel" expose="false" />

      <namespace name="System.Runtime.CompilerServices" expose="false" />

      <namespace name="System.Runtime.InteropServices" expose="false" />

</apiFilter>

 

Hope this helps. Cheers.

 

Anand..

Comments

  • Anonymous
    June 18, 2008
    PingBack from http://wordnew.acne-reveiw.info/?p=187

  • Anonymous
    June 18, 2008
    The comment has been removed

  • Anonymous
    June 18, 2008
    The comment has been removed

  • Anonymous
    June 19, 2008
    Hi I'm hoping I can use the filtering to only emit documentation for types and members that are marked with a certain attribute. For example, I might want specific documentation for [WebService], [WebMethod], [Serializable] In my case, I want to emit any types and members attributed with a custom attribute that is used for reflection-based interoperability between .NET and a non-CLR language. Could you provide an example please? Thanks for your great work and dedication!