如何让Stylecop在使用Sandcastle记录命名空间时停止抱怨

本文关键字：命名空间 记录 Sandcastle Stylecop | 更新日期: 2023-09-27 18:20:48

我正试图按照StackOverflow的答案的建议来记录我的命名空间

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帮助文件生成器中的设置更改为文档名称空间，但除非需要，否则我宁愿不更改，因为我希望所有文档都在源代码级别可用。我也不想完全禁用这些规则，因为它们在大多数情况下都很有用。

如何让Stylecop在使用Sandcastle记录命名空间时停止抱怨

我认为没有现成的解决方案。我认为，在保持干净的同时，你能做的最好的事情就是实现你自己的StyleCop规则。您可以考虑触发规则SA1402和SA1202的规则，除非在"SandCastle上下文"下。然后在StyleCop配置中禁用规则SA1402和SA1202。

您可以通过此链接了解如何为StyleCop创建规则。

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

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

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

这有点麻烦，因为我基本上只是添加了一个额外的文件来记录我的命名空间，但它确实让我的文档在项目和Sandcastle中保持100%的兼容性，而不会干扰Stylecop或我一直在使用的其他代码分析工具。

相关文章：