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

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


c# stylecop sandcastle
person Michael0x2a    schedule 02.07.2013    source источник

Ответы (2)


arrow_upward
1
arrow_downward

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

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

person Guillaume    schedule 02.07.2013

arrow_upward
1
arrow_downward

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

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

person Michael0x2a    schedule 03.08.2013