使用 Sandcastle 记录命名空间时，如何让 Stylecop 停止抱怨？答案

【问题标题】：How to get Stylecop to stop complaining when documenting namespaces using Sandcastle?使用 Sandcastle 记录命名空间时，如何让 Stylecop 停止抱怨？
【发布时间】：2013-07-02 00:01:40
【问题描述】：

我正在尝试按照this * 答案的建议记录我的命名空间：

namespace Test
{
    /// <summary>
    /// The documentation for my namespace goes here.
    /// </summary>
    [System.Runtime.CompilerServices.CompilerGenerated]
    internal class NamespaceDoc
    {
    }

    // (other classes below...)
}

但是，将此添加到我的文件会导致 StyleCop 发出几个错误。具体来说，它抱怨一个文档在根级别只能包含一个类（SA1402），并且所有内部类都必须在公共类之后（SA1202）。

我能够让 StyleCop 通过添加以下内容忽略第二个警告：

[System.Diagnostics.CodeAnalysis.SuppressMessage(
    "StyleCop.CSharp.OrderingRules", 
    "*", 
    Justification = "Hack for Sandcastle.")]

但是，我无法让它忽略第一个警告。我尝试应用另一个属性，但没有成功：

[System.Diagnostics.CodeAnalysis.SuppressMessage(
    "StyleCop.CSharp.Maintainability", 
    "*", 
    Justification = "Hack for Sandcastle.")]

让 Sandcastle 和 StyleCop 发挥出色的最佳方法是什么？

我知道我可以将 Sandcastle 帮助文件构建器中的设置更改为记录命名空间，但除非我需要，否则我宁愿不这样做，因为我希望所有文档都在源代码级别可用。我也不想完全禁用这些规则，因为它们在大多数情况下都很有用。

【问题讨论】：

标签： c# stylecop sandcastle

【解决方案1】：

我认为没有开箱即用的解决方案。我认为在保持清洁的同时你能做的最好的事情就是实施你自己的 StyleCop 规则。您可以考虑在“SandCastle 上下文”下触发规则 SA1402 和 SA1202 除非的规则。然后在 StyleCop 配置中禁用规则 SA1402 和 SA1202。

您可以查看如何为 StyleCop following this link 创建规则。

【讨论】：

【解决方案2】：

只是为了参考，我认为我应该记录我最终做了什么。

基本上，我只是为我拥有的每个命名空间创建了一个新的 .cs 文件（例如，FooDoc.cs 用于 Foo 命名空间），并将我的代码格式化如下：

// <copyright file="FooDoc.cs" company="Bar Company">
//      Copyright (c) 2013 Bar Company. All rights reserved.
// </copyright>

namespace Foo
{
    /// <summary>
    /// Documentation here.
    /// </summary>
    [System.Runtime.CompilerServices.CompilerGenerated]
    internal class FooDoc
    {
    }
}

这有点老套，因为我基本上是添加一个额外的文件来记录我的命名空间，但它确实让我将我的文档 100% 保存在项目中并且与 Sandcastle 兼容，而不会扰乱 Stylecop 或其他代码我一直在使用的分析工具。

【讨论】：