レベル2

C#のCS1587警告について解説

2025-03-29更新日: 2025-03-29

CS1587は、C#コンパイラがXMLコメントを許可されていない言語要素に記述された場合に表示する警告です。

たとえば、名前空間に対してドキュメントコメントを記述するとこの警告が発生します。

対象となる要素を確認し、コメントの箇所を適切に見直すことで警告を解消できます。

目次から探す

CS1587警告の基本

CS1587警告とは

CS1587警告は、C#のコンパイラがXMLドキュメントコメントを不適切な箇所に記述した場合に発生する警告です。

通常、XMLコメントはクラス、メソッド、プロパティなど、ドキュメント化が許可されている言語要素に対して利用されます。

名前空間のようにコメント対象として認められていない場合に、この警告が出力されます。

警告内容は、XMLコメントが有効な言語要素に対して使用されていないことを示しています。

XMLコメントの役割と使用範囲

XMLドキュメントコメントは、コードの説明や自動生成されるドキュメントの元となる情報を提供するために使用されます。

具体的には、以下のような用途があります。

クラス、構造体、インターフェース、メソッド、プロパティなど、ドキュメント化できる言語要素の説明
自動生成されるAPIリファレンスの補助
IntelliSenseでの表示情報の提供

しかし、名前空間やアセンブリなど、一部の要素にはXMLコメントを記述できないため、これらの対象に記述するとCS1587警告が発生します。

警告発生時の主要な注意事項

CS1587警告が発生した場合は、以下のポイントを確認してください。

XMLコメントが対象外の要素(たとえば名前空間)に付与されていないかを確認する
コメントタグが適切な位置に記述されているかを見直す
必要な場合は、対象の要素をクラスやメソッドなど、XMLコメントが許可されるものに修正する

発生原因と具体例

名前空間でのXMLコメント記述の誤り

XMLコメントは名前空間に対して認められていないため、名前空間の直前にXMLコメントを書いた場合、CS1587警告が発生します。

たとえば、以下のコードでは名前空間に対してコメントが付与されているため、警告が発生します。

サンプルコードに見るエラー発生パターン

以下のサンプルコードは、名前空間に不適切にXMLコメントを記述している例です。

// CS1587Sample.cs
// コンパイル例: csc /W:2 /doc:output.xml CS1587Sample.cs
/// <summary>サンプルの説明</summary>   // ※このXMLコメントは名前空間には使用できません
namespace SampleNamespace
{
    class Program
    {
        public static void Main()
        {
            // 実行内容は特になし
        }
    }
}

// このサンプルコードはコンパイル時にCS1587警告が発生します。

警告が引き起こされるその他のケース

XMLコメントを許可されない箇所に記述した場合は、名前空間以外にも発生する可能性があります。

たとえば、アセンブリレベルでのコメントや、特定の構文要素に対する誤った使用方法が考えられます。

プロジェクト内の全てのXMLコメントが、正しい言語要素に対して使用されているかを確認することが重要です。

エラー解消方法と修正手順

XMLコメント記述ルールの確認

エラーを解消するためには、Microsoftが提供するXMLドキュメントコメントの仕様を確認してください。

許可されているタグと、その使用範囲を理解することが大切です。

公式ドキュメントには、どの言語要素に対してXMLコメントが利用可能かが詳細に記述されています。

エラー解消のための具体的な修正例

CS1587警告を解消するには、対象のXMLコメントを適切な箇所に移動する必要があります。

たとえば、名前空間ではなく、その中のクラスにコメントを記述することで、警告を回避できます。

以下は修正例です。

// FixedSampleCode.cs
// コンパイル例: csc /W:2 /doc:output.xml FixedSampleCode.cs
namespace FixedNamespace
{
    /// <summary>FixedClassの説明</summary>
    class FixedClass
    {
        /// <summary>Main関数の説明。この関数はプログラムのエントリーポイントです。</summary>
        public static void Main()
        {
            // 出力サンプル：修正されたXMLコメントのコードです
            System.Console.WriteLine("XMLコメントが正しい場所にあります");
        }
    }
}

XMLコメントが正しい場所にあります

コンパイルオプションとの関連確認

XMLドキュメントファイルを生成するためには、/docオプションを使用します。

このオプションがプロジェクト設定やビルドスクリプトに正しく指定されているか確認してください。

また、警告レベルを指定するオプション(例えば/W:2)も、開発環境に合わせて適切に設定することで、警告の把握が容易になります。

実践的な検証とコード例

エラー再現手順の解説

まず、エラーを再現するための手順を説明します。

以下の手順に沿って進めることで、CS1587警告がどのように発生するか確認できます。

新規C#プロジェクトを作成する
プロジェクトのソースコードに、名前空間の直前にXMLコメントを記述する
コンパイルを実行し、警告が表示されることを確認する

以下に、エラー再現用のサンプルコードを示します。

// ReproduceError.cs
// コンパイル例: csc /W:2 /doc:output.xml ReproduceError.cs
/// <summary>エラー再現用のXMLコメント</summary>   // この位置にコメントを書くと警告が発生します
namespace ErrorNamespace
{
    class Program
    {
        public static void Main()
        {
            // 警告発生のテスト用コード
            System.Console.WriteLine("CS1587警告の再現");
        }
    }
}

CS1587警告の再現

修正前後のコード比較

以下は、XMLコメントの誤った記述方法と修正後のコードの比較です。

修正前(誤った記述例)
- 名前空間の直前にXMLコメントが記述されている
修正後(正しい記述例)
- XMLコメントはクラスやメソッドなど、コメント対象として許可された要素に記述されている

具体的には、修正前は以下のようになります。

/// <summary>誤ったコメント記述</summary>   // 警告対象
namespace ErrorNamespace
{
    // ...
}

修正後は、名前空間外に移動してクラス内部に記述します。

namespace CorrectNamespace
{
    /// <summary>正しいコメント記述</summary>
    class Program
    {
        public static void Main()
        {
            // 正常な出力が行われるコード
            System.Console.WriteLine("正しく修正されたコード");
        }
    }
}

コード例から見る修正のポイント

修正のポイントは、XMLコメントが適用される対象は必ず言語仕様で許可されているものでなければならないという点です。

具体的には：

名前空間の直前にXMLコメントを記述しない
クラス、メソッド、プロパティなど、ドキュメントコメントが認められている要素にのみ記述する
誤っている場合は、コメントを削除または移動する

追加の注意点と参考情報

XMLコメント推奨タグの使用制限

XMLドキュメントコメントでは、特定の推奨タグのみが使用可能です。

たとえば、<summary>、<remarks>、<param>、<returns>などが一般的に使用されます。

許可されていないタグや、誤った位置での記述は、警告の原因となるため注意が必要です。

また、コメントが意味を持つ要素に対して適切に配置されているか、コードレビューなどで確認する習慣を持つと良いでしょう。

Microsoft公式ドキュメントの参照方法

最新の情報や詳細な仕様については、Microsoftの公式ドキュメントで確認できます。

公式ドキュメントには、XMLコメントの記述ルールや推奨されるタグの一覧、使用例が豊富に掲載されています。

開発の際に疑問が生じた場合は、公式資料を参照することで、正確な情報を手に入れることができます。

まとめ

この記事では、CS1587警告の概要やXMLドキュメントコメントが適用可能な対象、警告の発生する主な原因とその再現例、エラー解消方法や具体的な修正手順について学べます。

適切な対象にコメントを記述することで警告回避が可能となり、Microsoft公式資料を参照することで最新の情報を把握できる内容となっています。