Looking for Stylecop-perfect comments for `protected override void Dispose(bool disposing)`.

Question

I know, StyleCop is not perfect, but we try to use it in a helpful way. I do like the fact that it complains about undocumented arguments. Now, for properties and constructors it recommends what the text should be, but it does not help with Dispose method, and I think it should. We have many classes that implement IDisposable. In this particular case the class is a WinForm. The trouble is that I have not been able to come up with great documentation for the Dispose method, and I have not seen a good example online either. Many examples have no comment whatsoever. I am hoping that someone who feels like Dispose method is a second nature to them, can help me document this once and for all, so that I can re-use this comment everywhere.

Here is what we have:

    /// <summary>
    /// Clean up any resources being used.
    /// </summary>
    protected override void Dispose(bool disposing)
    {
        if (disposing)
        {
            if (this.components != null)
            {
                this.components.Dispose();
            }
        }

        base.Dispose(disposing);
    }

And here is the warning message:

Warning 15 SA1611: The documentation header must contain param tags matching the element's parameter list.  

I hope that other So users will find the answer to this helpful as well. Let me know if you have questions.

Answer 1

This is auto-generated code from a project template. The only real fix is to alter the template or edit the Designer.cs source code file. The template is in Common7\IDE\ItemsTemplate(Cache)\CSharp\Windows Forms\xxxx\Form.zip\form.designer.cs. Editing it will of course only fix the problem for future projects.

Editing auto-generated code isn't normally the greatest idea, but you'll get away with it in this particular case.

Answer 2

There are some good comments here but it doesn't go so far to be StyleCop-compliant. What you need is this:

/// <summary>
/// Releases the unmanaged resources used by this
/// class and optionally releases the managed resources.
/// </summary>
/// <param name="disposing">True to release both managed and unmanaged
/// resources; false to release only unmanaged resources.</param>

Hope this helps!

Answer 3

You could investigate using GhostDoc. It will often search through the the inheritance tree and find comments from parent classes. In this case as the Dispose method is overridden it would find meaningful comments.