Filtering Event Handler Delegates from Sandcastle docs RRS feed

  • Question

  • I am building documentation for a VB library using the March CTP (Refresh) and SHFB  (in Prototype style) and have an issue with the way the documentation handles event delegates.

    For my purposes I'd be fine to just exclude the EventHandler delegates from the help file.
    I have found some mentions of sandcastle.config entries for <apiFilter>, but no real in depth explanation of the feature.

    Can you use apiFilter to somehow exclude all delegate declarations?

    Here is some additional background on the reasons I want to exclude the event handlers from the help.

    Here is a Simplified example..

    Public Class MyClass
        Public Event Example( sender as Object args as EventArgs )
    End Class

    The Delegate for that event is MyClass.ExampleEventHandler.

    In the TOC it is properly named, but alphabetized under "ExampleEventHandler" instead of the full name. Also it shows in the sample (top) level as the "MyClass" class, instead on nested inside of it like its methods and properties are. (Sidenote: it would be great of contained classes also nested inside the main class!)

    On the Namespace summary page, all event handler delegates are shown (like in the TOC), but they are not qualified by their containing class, so if you have the same event name on multiple classer, the handler name is shown multiple times).

    Overall, the Event Handler delegates just seem like noise in the help file.

    Would anyone else consider the event handler display a problem?
    Is it possible to use the apiFilter as a workaround?


    Wednesday, March 21, 2007 9:30 PM

All replies

  • I am checking but I do not believe we designed the ripping for this scenario.



    Thursday, March 22, 2007 6:43 AM
  • Thanks.

    I looked at the standard MSDN docs and I see now that the delegates are normally coded at the same level in the namespace as the class with a name that is prepended with the class name that raises the event.

    However, because I am using VB, it automatically generates the handler delegate _contained_ by the event class. So then with the TOC sorting and namespace summary page bugs with those contained classes, the presentation in the help ends up seeming more abnormal.

    Following that C# pattern, the generated help would be normal and goes to understanding why more people aren't seeing what I necessarily see.

    If I was coding the handler delegates manually (in C#), I guess I could just add the <exclude> xml comment if I wanted then skipped, but in VB I don't have that opportunity.

    Anyway, just wanted to provide some more insight on documenting VB projects.

    Monday, March 26, 2007 2:31 PM