views:

410

answers:

2

I have seen this in a lot of XML comments for classes in the .NET Framework BCL but have never been able to find documentation that explains what it does.

As an example, looking at System.Object reveals the following comments:

namespace System   
{
    /// <summary>Supports all classes in the .NET Framework class hierarchy 
    /// and provides low-level services to derived classes. This is the 
    /// ultimate base class of all classes in the .NET Framework; it is the
    /// root of the type hierarchy.</summary>
    /// <filterpriority>1</filterpriority> 
    [System.Runtime.InteropServices.ClassInterfaceAttribute(2)]
    public class Object    
    {    
        /// <summary>Determines whether the specified 
        /// <see cref="T:System.Object" /> 
        /// instances are considered equal.</summary>  
        /// <returns>true if objA is the same instance as objB or
        /// if both are null
        /// references or if objA.Equals(objB) returns true; 
        /// otherwise, false.</returns>
        /// <param name="objB">The second <see cref="T:System.Object" /> 
        /// to compare. </param>
        /// <param name="objA">The first <see cref="T:System.Object" /> 
        /// to compare. </param>
        /// <filterpriority>2</filterpriority>
        public static bool Equals(object objA, object objB);
     }
 }
+3  A: 

Just a guess: the All vs Common tabs in intellisense?

Joel Coehoorn
That could be, but those tabs are only available in the IDE for VB projects not C#. So, if this really is a C# only feature that wouldn't apply.
Scott Dorman
Turns out you are correct and this is a VB only feature. A filterpriority = 2 is equiavalent to EditorBrowsable(EditorBrowsableState.Advanced) and the method only shows up on the "All" tab. You do need to have an XML comment file generated in order for this to work. C# appears to ignore the comment.
Scott Dorman
Can you post a link to where you found that? I'm curious because I wonder how it would behave if the xml disagreed with the attribute.
Joel Coehoorn
Your and Øyvind's comments comibined with http://issuu.com/pchew/docs/xml_document_guide/31. Added some actual testing in a VB and C# project got me the rest of the way. In the process of writing a full blog post about this. Will post the link when it's done.
Scott Dorman
There is some interplay between the attribute and the xml but it changes as to which one takes precedence based on the value of both. More details in the blog post.
Scott Dorman
Ok...blog post is at: http://geekswithblogs.net/sdorman/archive/2009/01/08/xml-comments-filterpriority.aspx
Scott Dorman
+2  A: 

It is the same as decorating your member with EditorBrowsableAttribute. I would guess values 0,1 and 2 corresponds to Always, Advanced and Never.

Øyvind Skaar
How is an XML comment the same as decorating with the EditorBrowsableAttribute?
Scott Dorman
To be more precise; it has the same effect in Visual Studio. It governs what members not to display in the Intellisense dropdown list.
Øyvind Skaar
Turns out Joel was correct and that this determines the intellisense tab the method appears on in VB.NET. You are also correct in that it provides the same behavior on intellisense as the EditorBrowsable(EditorBrowsableState.Advanced) attribute.
Scott Dorman