ドキュメントコメントの書き方、使い方

2021年3月9日

VisualStudioを使っていると、インテリセンスでヒントが表示され、開発のヘルプになっているのが便利ですね。
これは、自作のクラス、メソッド、コンストラクタなど多くのところでも使うことができます。
クラスが複数に分かれている場合、どのように機能を持っているのかいちいちコードに戻って調べることなく、概要を知ることができます。では、これを実現する方法を見ていきましょう。

次のような表示を出すことができます。

元のコード

using UnityEngine;

class Player
{
    public int Hp { get; set; }
}

public class Sample : MonoBehaviour
{
    Player player;

    void Start()
    {
        player = new Player();
        player.Hp = 10;
        Debug.Log(player.Hp);
    }
}

1. クラスのドキュメントコメント
2. プロパティのドキュメントコメント
3. メソッドのドキュメントコメント
4. 複数行の概要を記入する
5. コメントを折りたたむ
6. オーバーロード
7. ドキュメントを文章にして、ブラウザで表示できるようにする方法
8. 参考

クラスのドキュメントコメント

class Playerの上の行に次のように///を入力します

///
class Player
{
    public int Hp { get; set; }
}

３つ目の/を入力した時点で次のような表示になると思います

/// <summary>
/// 
/// </summary>
class Player
{
    public int Hp { get; set; }
}

<summary> と </summary>の間に概要を入力します

/// <summary>
/// これは、私が作ったクラスです
/// </summary>
class Player
{
    public int Hp { get; set; }
}

これで、ホバーのヒントが表示されるようになりました。

プロパティのドキュメントコメント

まず、結果ですが次のようになります。

クラスの時の作成と同じようにします

/// <summary>
/// これは、私が作ったクラスです
/// </summary>
class Player
{
    /// <summary>
    /// ヒットポイント
    /// </summary>
    public int Hp { get; set; }
}

メソッドのドキュメントコメント

まず、結果ですが次のようになります。

入力中にメソッドの引数の説明を表示

元のコード

using UnityEngine;

class Player
{
    public string Double(int value)
    {
        return $"{value} の　２倍は　{value * 2} です";
    }
}

public class Sample : MonoBehaviour
{
    Player player;

    void Start()
    {
        player = new Player();
        Debug.Log(player.Double(3));
    }
}

この場合も同じように///を入力します。
自動で、次のようなコードが生成されます

    /// <summary>
    /// 
    /// </summary>
    /// <param name="value"></param>
    /// <returns></returns>
    public string Double(int value)

<param>は、パラメータのことです。引数ですね。
<return>は、戻り値です。

次のようにコメントを追加します。

using UnityEngine;

class Player
{
    /// <summary>
    /// 整数を２倍にする
    /// </summary>
    /// <param name="value">２倍にしたい元の整数</param>
    /// <returns>２倍にした結果</returns>
    public string Double(int value)
    {
        return $"{value} の　２倍は　{value * 2} です";
    }
}

public class Sample : MonoBehaviour
{
    Player player;

    void Start()
    {
        player = new Player();
        Debug.Log(player.Double(3));
    }
}

複数行の概要を記入する

1行目を入力後、エンター（改行）キーで、次の行入力ができます。

/// <summary>
/// これは、私が作ったクラスです
/// 2行目のコメント
/// 3行目のコメント
/// </summary>
class Player
{
    public int Hp { get; set; }
}

コメントを折りたたむ

ドキュメントコメントは複数行に渡りますので、コードの見通しが悪いなと感じたら折りたたむことで解消できます

折りたたむ前

折りたたんだ後

オーバーロード

メソッドのオーバーロード場合、どのようになるかみてみましょう

class Player
{
    /// <summary>
    /// 足し算
    /// </summary>
    /// <param name="val1">1つ目の整数</param>
    /// <param name="val2">2つ目の整数</param>
    public void Add(int val1, int val2)
    {
        Debug.Log(val1 + val2);
    }

    /// <summary>
    /// 足し算
    /// </summary>
    /// <param name="val1">1つ目の整数</param>
    /// <param name="val2">2つ目の整数</param>
    /// <param name="val3">3つ目の整数</param>
    public void Add(int val1, int val2, int val3)
    {
        Debug.Log(val1 + val2 + val3);
    }
}

呼び出し側で確認してみましょう。
途中まで入力すると、+1オーバーロードと表示されます