How to document a class property

What is the c开发者_高级运维orrect syntax for an XML comment for a class property?

In response to a request for explicit examples, the following extract is from StyleCop help document, "SA1623: PropertySummaryDocumentationMustMatchAccessors":

The property’s summary text must begin with wording describing the types of accessors exposed within the property. If the property contains only a get accessor, the summary must begin with the word “Gets”. If the property contains only a set accessor, the summary must begin with the word “Sets”. If the property exposes both a get and set accessor, the summary text must begin with “Gets or sets”.

For example, consider the following property, which exposes both a get and set accessor. The summary text begins with the words “Gets or sets”.

/// <summary>
/// Gets or sets the name of the customer. 
/// </summary>
public string Name
{
    get { return this.name; }
    set { this.name = value; }
}

If the property returns a Boolean value, an additional rule is applied. The summary text for Boolean properties must contain the words “Gets a value indicating whether”, “Sets a value indicating whether”, or “Gets or sets a value indicating whether”. For example, consider the following Boolean property, which only exposes a get accessor:

/// <summary>
/// Gets a value indicating whether the item is enabled.
/// </summary>
public bool Enabled
{
    get { return this.enabled; }
}

In some situations, the set accessor for a property can have more restricted access than the get accessor. For example:

/// <summary>
/// Gets the name of the customer. 
/// </summary>
public string Name
{
    get { return this.name; }
    private set { this.name = value; }
}

In this example, the set accessor has been given private access, meaning that it can only be accessed by local members of the class in which it is contained. The get accessor, however, inherits its access from the parent property, thus it can be accessed by any caller, since the property has public access.

In this case, the documentation summary text should avoid referring to the set accessor, since it is not visible to external callers.

StyleCop applies a series of rules to determine when the set accessor should be referenced in the property’s summary documentation. In general, these rules require the set accessor to be referenced whenever it is visible to the same set of callers as the get accessor, or whenever it is visible to external classes or inheriting classes.

The specific rules for determining whether to include the set accessor in the property’s summary documentation are:

1.The set accessor has the same access level as the get accessor. For example:

/// <summary>
/// Gets or sets the name of the customer. 
/// </summary>
protected string Name
{
    get { return this.name; }
    set { this.name = value; }
}

2.The property is only internally accessible within the assembly, and the set accessor also has internal access. For example:

internal class Class1
{
    /// <summary>
    /// Gets or sets the name of the customer. 
    /// </summary>
    protected string Name
    {
        get { return this.name; }
        internal set { this.name = value; }
    }
}

internal class Class1
{
    public class Class2
    {
        /// <summary>
        /// Gets or sets the name of the customer. 
        /// </summary>
        public string Name
        {
            get { return this.name; }
            internal set { this.name = value; }
        }
    }
}

3.The property is private or is contained beneath a private class, and the set accessor has any access modifier other than private. In the example below, the access modifier declared on the set accessor has no meaning, since the set accessor is contained within a private class and thus cannot be seen by other classes outside of Class1. This effectively gives the set accessor the same access level as the get accessor.

public class Class1
{
    private class Class2
    {
        public class Class3
        {
            /// <summary>
            /// Gets or sets the name of the customer. 
            /// </summary>
            public string Name
            {
                get { return this.name; }
                internal set { this.name = value; }
            }
        }
    }
}

4.Whenever the set accessor has protected or protected internal access, it should be referenced in the documentation. A protected or protected internal set accessor can always been seen by a class inheriting from the class containing the property.

internal class Class1
{
    public class Class2
    {
        /// <summary>
        /// Gets or sets the name of the customer. 
        /// </summary>
        internal string Name
        {
            get { return this.name; }
            protected set { this.name = value; }
        }
    }

    private class Class3 : Class2
    {
        public Class3(string name) { this.Name = name; }
    }
}

Install this: http://submain.com/products/ghostdoc.aspx

Right-click on the property, select 'Document This'. Fill in the blanks.

According to MSDN, link, it appears there isn't an official tag for Class Properties. But, I would use something like this:

/// <summary>Here is an example of a propertylist:
/// <list type="Properties">
/// <item>
/// <description>Property 1.</description>
/// </item>
/// <item>
/// <description>Property 2.</description>
/// </item>
/// </list>
/// </summary>

I'd suggest to use StyleCop. It does not only enforce (a bit to strong for my taste) you to comment, but also gives you a hint how the comments should be startet.

According to C# documentation the keyword <value> is used to desrcibe properties.

Implementation would look like this:

/// <value>Description goes here.</value>
public string MyProperty { get; set; }

source: https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/language-specification/documentation-comments#d319-value

Using <summary> should work too and even though I'm still learning C# it seems the documentation is more of a recommendation than a PEP8-like guide. So I think as long as one's code is consistent it comes down to personal preference and/or company guidelines.