1

このStackOverflowの回答で推奨されているように、名前空間を文書化しようとしています:

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

    // (other classes below...)
}

ただし、これをファイルに追加すると、StyleCop でいくつかのエラーが発生しました。具体的には、ドキュメントにはルート レベルで 1 つのクラスのみを含めることができ (SA1402)、すべての内部クラスはパブリック クラスの後に配置する必要がある (SA1202) と主張しました。

以下を追加することで、StyleCop に 2 番目の警告を無視させることができました。

[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 ヘルプ ファイル ビルダー内の設定を名前空間をドキュメント化するように変更できることはわかっていますが、すべてのドキュメントをソース コード レベルで利用できるようにしたいので、必要がない限り変更したくありません。また、ほとんどの状況で役立つため、ルールを完全に無効にしたくありません。

4

2 に答える 2

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% 維持し、Stylecop やその他のコード分析ツールを混乱させることなく、Sandcastle 互換性を保つことができます。使ってきました。

于 2013-08-03T00:03:28.590 に答える
1

箱から出して解決策はないと思います。物事をきれいに保ちながらできる最善のことは、独自の StyleCop ルールを実装することだと思います。「SandCastle コンテキスト」でない限り、ルール SA1402 および SA1202 をトリガーするルールを検討できます。次に、StyleCop 構成で、ルール SA1402 および SA1202 を無効にします。

このリンクに従って、StyleCop のルールを作成する方法を確認できます。

于 2013-07-02T02:01:12.663 に答える