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

Я пытаюсь задокументировать свои пространства имен, как рекомендовано в ответе Stackru:

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

Источник

2 ответа

Решение

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

В основном, я только что создал новый .cs файл для каждого пространства имен, которое у меня было (например, FooDoc.cs для Foo namespace) и отформатировал мой код так:

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

Источник

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

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

Источник
Другие вопросы по тегам