【C#】ドキュメントコメントの使い方を解説します

こんにちは。たいら(@tairaengineer2)です。
この記事では、C#で使われているドキュメントコメントの使い方を解説します。

スポンサーリンク

前提条件

この記事では、Visual Studio 2017 Communityを使っています。
インストールの仕方は、下の記事をご参考ください。

www.tairax.com

ドキュメントコメントとは

ドキュメントコメントとは、C#で使われるxml形式で書くコメントです。

ドキュメント コメント
C# プログラマを XML テキストを含む特殊なコメント構文を使用してコードを文書化するためのメカニズムを提供します。
ソース コード ファイルでこのようなコメントとその直後にあるソース コード要素から XML を生成するツールに指示する特定の形式のコメントを使用できます。

ドキュメント コメントDocumentation comments - C# language specification | Microsoft Docsから引用させて頂きました

下の画像でいうと赤枠で囲っているのがドキュメントコメントです。

使い方を覚えておくと便利です。

コメントの使い方を解説

よく使うであろうタグを抜粋して実際の使用例を使って解説します。
解説するタグは

• paramタグ
• remarksタグ
• returnsタグ
• summaryタグ

上記4タグを解説します。

スポンサーリンク

paramタグ

この章では、paramタグについて解説します。

paramタグとは

<param> (C# プログラミング ガイド)

構文
<param name="name">description</param>  

パラメーター
name
メソッド パラメーターの名前です。
名前は二重引用符 (" ") で囲みます。
description
パラメーターの説明です。

解説
<param> タグは、メソッドのいずれか 1 つのパラメーターを説明するためにメソッドの宣言のコメントで使用する必要があります。
複数のパラメーターをドキュメント化するには、複数の <param> タグを使用します。

paramタグ(C# プログラミング ガイド)から引用させて頂きました

paramタグは、

• コンストラクタ
• メソッド

の引数を説明するときに使います。

paramタグの使用例

namespace ConsoleApp1
{
    /// <summary>
    /// イヌクラス
    /// </summary>
    class Dog
    {
        /// <summary>
        /// コンストラクタ
        /// </summary>
        public Dog()
        {
        }

        /// <summary>
        /// コンストラクタ
        /// </summary>
        /// <param name="name">名前</param>
        /// <param name="age">年齢</param>
        public Dog(string name, int age)
        {
            Name = name;
            Age = age;
        }

        /// <summary>
        /// イヌの飼い主のメッセージを取得
        /// </summary>
        /// <param name="ownerAge">年齢</param>
        /// <param name="ownerName">名前</param>
        /// <returns>メッセージ</returns>
        public string GetDogMessage(int ownerAge, string ownerName)
        {
            return $"{Name}の飼い主の名前は{ownerName},年齢は{ownerAge}歳";
        }

        /// <summary> 名前 </summary>
        public string Name { get; set; }
        /// <summary> 年齢 </summary>
        public int Age { get; set; }
    }
}

remarksタグ

この章では、remarksタグについて解説します。

remarksタグとは

<remarks> (C# プログラミング ガイド)

構文
<remarks>description</remarks>  

パラメーター
Description
メンバーの説明。

解説
<remarks> タグを使用して、型の情報を追加し、<summary> で指定された情報を補足します。 

remarksタグ(C# プログラミング ガイド)から引用させて頂きました

remarksタグは、summaryタグで書いた情報の補足として使われます。
remarksタグはsummaryタグの直下に書きます。

remarksタグの使用例

using System;

namespace ConsoleApp1
{
    /// <summary>
    /// イヌクラス
    /// </summary>
    /// <remarks>ペットのイヌ</remarks>
    class Dog
    {
        /// <summary>
        /// コンストラクタ
        /// </summary>
        /// <remarks>引数なし</remarks>
        public Dog()
        {
        }

        /// <summary>
        /// コンストラクタ
        /// </summary>
        /// <remarks>引数2つ</remarks>
        /// <param name="name">名前</param>
        /// <param name="age">年齢</param>
        public Dog(string name, int age)
        {
            Name = name;
            Age = age;
        }

        /// <summary>
        /// イヌの飼い主のメッセージを取得
        /// </summary>
        /// <remarks>飼い主を説明するメッセージ</remarks>
        /// <param name="ownerAge">年齢</param>
        /// <param name="ownerName">名前</param>
        /// <returns>メッセージ</returns>
        public string GetDogMessage(int ownerAge, string ownerName)
        {
            return $"{Name}の飼い主の名前は{ownerName},年齢は{ownerAge}歳";
        }

        /// <summary> 名前 </summary>
        public string Name { get; set; }
        /// <summary> 年齢 </summary>
        public int Age { get; set; }
    }
}

returnsタグ

この章では、returnsタグについて解説します。

returnsタグとは

<returns> (C# プログラミング ガイド)

構文
<returns>description</returns>

パラメーター
description
戻り値の説明。

解説
<returns> タグは、戻り値を説明するためにメソッドの宣言のコメントで使用する必要があります。

returnsタグ(C# プログラミング ガイド)から引用させて頂きました

returnsタグはメソッドの戻り値はどんな内容かを書くタグです。
メソッドの戻り値が何もない（void）の場合は、書かなくてOKです。

remarksタグの使用例

using System;

namespace ConsoleApp1
{
    /// <summary>
    /// イヌクラス
    /// </summary>
    class Dog
    {
        /// <summary>
        /// コンストラクタ
        /// </summary>
        public Dog()
        {
        }

        /// <summary>
        /// コンストラクタ
        /// </summary>
        /// <param name="name">名前</param>
        /// <param name="age">年齢</param>
        public Dog(string name, int age)
        {
            Name = name;
            Age = age;
        }

        /// <summary>
        /// イヌの飼い主のメッセージを取得
        /// </summary>
        /// <param name="ownerAge">年齢</param>
        /// <param name="ownerName">名前</param>
        /// <returns>メッセージ</returns>
        public string GetDogMessage(int ownerAge, string ownerName)
        {
            return $"{Name}の飼い主の名前は{ownerName},年齢は{ownerAge}歳";
        }

        /// <summary>
        /// イヌの情報をコンソールに表示する
        /// </summary>
        public void DisplayDogInfo()
        {
            Console.WriteLine($"イヌの名前は{Name},年齢は{Age}歳");
        }

        /// <summary> 名前 </summary>
        public string Name { get; set; }
        /// <summary> 年齢 </summary>
        public int Age { get; set; }
    }
}

summaryタグ

この章では、summaryタグについて解説します。

summaryタグとは

<summary> (C# プログラミング ガイド)

構文
<summary>description</summary> 

パラメーター
description
オブジェクトの概要。

解説
<summary> タグは、型または型のメンバーの説明に使用します。
型の説明に補足情報を追加するには、<remarks> タグを使用します。

summaryタグ(C# プログラミング ガイド)から引用させて頂きました

summaryタグはよく

• クラス
• メソッド

の上に書いて、説明するときに使われます。

summaryタグの使用例

namespace ConsoleApp1
{
    /// <summary>
    /// イヌクラスの説明をします
    /// </summary>
    class Dog
    {
        /// <summary>
        /// コンストラクタ
        /// </summary>
        public Dog()
        {
        }
    }
}

スポンサーリンク

まとめ：ドキュメントコメントを使ってみよう

以上がドキュメントコメントについて解説です。
まとめなので軽く振り返ってみると

paramタグ	コンストラクタ メソッド の引数を説明するときに使う
remarksタグ	summaryタグの補足で使われる
returnsタグ	メソッドの戻り値を説明するときに使われる
summaryタグ	クラス メソッド の上に書いて、説明するときに使われる

あなたのご参考になったのなら、とても嬉しいです(*´▽｀*)
ではでは～(・ω・)ﾉｼ

ほかにもC#勉強記事を書いてます。
よければご参考ください。

【C#】コンソールでHellow,Worldを表示させる

【C#】はてな2つの演算子、null合体演算子について解説します

今までブログで書いたC#の解説記事のまとめは、こちらをご参考ください。

【C#】ブログで書いた文法記事のまとめ