What should I include in XML documentation comments?

Question

I'm trying to make a point of documenting my code better, especially when it comes to the XML comments on class members, but often it just feels silly.

In the case of event handlers, the naming convention and parameters are standard and clear:

/// <summary>
/// Handler for myCollection's CollectionChanged Event.
/// </summary>
/// <param name="sender">Event Sender</param>
/// <param name="e">Event Arguments</param>
private void myCollection_CollectionChanged(object sender, NotifyCollectionChangedEventArgs e)
{
    // actual code here...
}

I also frequently have simple properties that are (IMO) named clearly so that the summary is redundant:

/// <summary>
/// Indicates if an item is selected.
/// </summary>
public bool ItemIsSelected
{ get { return (SelectedItem != null); } }

I don't feel like such comments don't add any information that the declaration itself doesn't already convey. The general wisdom seems to be that a comment that repeats the code is best left unwritten.

Obviously, XML documentation is more than just regular inline code comments, and ideally will have 100% coverage. What should I be writing in such cases? If these examples are OK, what value do they add that I may not be appreciating now?

Answer 1

XML doc comments are intended for public members.

The compiler warning clearly states this:

Missing XML comment for publicly visible type or member 'Type_or_Member'

You should only add XML comments to private members if those members aren't already obvious from their names.

Answer 2

Pure opinion here, so take it for what it's worth.

I hate superfluous xml comments. Doubly so for the ghost doc style ones that simply add spaces to the method/property name. It adds no value and simply clutters my view of the actual code.

If something needs clarification, by all means, comment it. However, a lot of clarity can be conveyed by small focused methods with meaningful names. Don't comment code if you can improve it and make the comment unnecessary.

Don't even get me started on the unnecessary use of this. and Me..

As a side note, I would love to have a Visual Studio addin that let me toggle the visibility of xml comments. (hint, hint)

Answer 3

On a public member XML documents should be fairly verbose and complete, as @SLaks has mentioned.

However they can be really useful on private, protected or internal members too because Visual Studio will populate intellisense and help tooltips with the XML doc comments.

This means that:

// describe what this does
private void DoSomething() 
{
    // or describe it here...

Might be perfectly sufficient documentation, but:

/// <summary>describe what this does</summary>
private void DoSomething() 
{

Will be much easier to see quickly from elsewhere in your code.

Generally on public XML comments I'm writing for some external user of the API, and on internal XML comments I'm writing for me or others on my team.

Skipping parameter descriptions is probably a bad idea for the former and fine for the latter.

I would add (in public API docs especially) always include whether get or set on properties:

/// <summary>Gets a value indicating whether an item is selected.</summary>
public bool ItemIsSelected
{ 
    get { return SelectedItem != null; } 
}

It's not obvious from C#'s intellisense whether get or set are available, but putting it on the XML comment will mean you can tell at a glance from the tooltip.