Filtering APIs using Sandcastle


 


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 (4)

  1. SelormeyPaul says:

    @Anand: Hope this helps.

    Yes, thank you very much.

    Now, I wish you could add configuration of the IntellisenseComponent2 component 🙂

    Can we use contents of your blog for Sandcastle tools and components documentations?

    With the Sandcastle Assist project, we hope to provide configuration classes for all the built-in components and the documentations will help a lot.

    Best regards,

    Paul.

  2. aram says:

    Hi Paul,

    Please feel free to reuse the docs from this site and also update them. Yes I will send you answers to the Intellisense component.

    Anand..

  3. cjm55 says:

    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!