寻找 Stylecop 完美注释“protected override void Dispose(bool disducing)”

Question

我知道，StyleCop 并不完美，但我们尝试以有用的方式使用它。我确实喜欢它抱怨未记录的论点。现在，对于属性和构造函数，它建议文本应该是什么，但它对 Dispose 方法没有帮助，但我认为应该如此。我们有许多实现IDisposable的类。在这种特殊情况下，该类是一个WinForm。问题是我无法为 Dispose 方法提供很好的文档，而且我也没有在网上看到一个很好的例子。许多例子没有任何评论。我希望那些觉得 Dispose 方法是他们的第二天性的人，可以帮助我一劳永逸地记录这一点，以便我可以在任何地方重复使用这个评论。

这是我们所得到的：

    /// <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);
    }

这是警告消息：

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

我希望其他 So 用户也会发现这个问题的答案也很有帮助。 如果您有疑问，请告诉我。

Answer 1

这是从项目模板自动生成的代码。唯一真正的修复方法是更改​​模板或编辑 Designer.cs 源代码文件。模板位于 Common7\IDE\ItemsTemplate(Cache)\CSharp\Windows Forms\xxxx\Form.zip\form.designer.cs 中。编辑它当然只会解决未来项目的问题。

编辑自动生成的代码通常不是最好的主意，但在这种特殊情况下您会侥幸逃脱。

Answer 2

此处有一些很好的评论，但没有到目前为止符合 StyleCop。您需要的是：

/// <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>

希望这会有所帮助！

Answer 3

您可以使用 GhostDoc 进行调查。它经常会搜索继承树并查找父类的注释。在这种情况下，当 Dispose 方法被重写时，它将找到有意义的注释。