Как заставить Stylecop перестать жаловаться при регистрации пространств имен с помощью Sandcastle?

Question

Я пытаюсь документировать свои пространства имен в соответствии с рекомендациями this 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 для документирования пространств имен, но я бы предпочел, если это не понадобится, потому что я хочу, чтобы вся документация была доступна на уровне исходного кода. Я также не хочу полностью отключать правила вообще, потому что они являются полезными в большинстве случаев.

Answer 1

Только для справки, хотя я должен документировать то, что я закончил делать.

В принципе, я просто создал новый .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, ни другие инструменты анализа кода, которые я использовал.

Answer 2

Я не думаю, что есть какое-либо решение из коробки. Я думаю, что лучшее, что вы можете сделать, сохраняя чистоту, - это реализовать свое собственное правило StyleCop. Вы можете рассмотреть правило, которое запускает правила SA1402 и SA1202 , если в контексте «SandCastle context». Затем в вашей конфигурации StyleCop вы отключите правила SA1402 и SA1202.

Вы можете посмотреть, как создать правило для StyleCop following this link.