EditorBrowsable attributes

Topics: User Forum
Sep 17, 2009 at 4:26 PM

I use [EditorBrowsable(EditorBrowsableState.Never)] on many things to filter them out of Intellisense and the Visual Studio Object Browser, so I need to synchronize those exclusions with the help file.  As I understand it, <exclude /> in the source code has no effect.  I am thinking about writing a tool that reads my assembly and the shfbproj file and ensures an ApiFilter Filter node exists if and only if something has EditorBrowsableState.Never.  Maybe the best approach will be to use your API.  Any advice?   I don't see much alternative, because manually resolving  discrepancies between things exposed in Help vs. Visual Studio, via the interactive ApiFilter, would be an ongoing task we want to eliminate.

Coordinator
Sep 17, 2009 at 8:34 PM

SHFB supports removal of items using the <exclude /> XML comment tag.  It scans the XML comments and automatically adds items to the API filter if it finds an <exclude /> tag.  If you don't mind adding the tags to the code, it's probably the simplest approach.  If you did want to make it more automatic and avoid adding the tags to the code, you could write a plug-in that runs before the ApplyVisibilityProperties build step that strips out members that contain that attribute.  You'd load the generated reflection.xml file, search for any member containing the attribute, and remove it and the corresponding element from the parent class's API entry.

Using an API filter is generally more efficient though since the MRefBuilder tool will strip out the members as it produces the reflection information.  See the help file for more information on creating a plug-in.  You might take a look at the existing XPath Reflection File Filter plug-in since it may be of use or may be something you can use as a basis for your own custom plug-in.  Note that currently, it runs after the build step rather than before so if you aren't documenting attributes (the DocumentAttributes project property is set to false), they'd have been removed already.  Making it run before the build step is a simple matter of changing the execution point definition.

Eric

 

Sep 17, 2009 at 10:47 PM

Thanks.  My best best is to do this:

/// <exclude />
[EditorBrowsable(EditorBrowsableState.Never)]

public class InHouseOnly { 

}

It is now clear to me that if the ApiFilter is (None), the builder considers it to contain exclusions from the XML comments.  When the ApiFilter is edited, it is initialized from those comments, and if that project file is saved, its explicit Filter settings now override the presence or absence of XML exclude tags.