VisualStudio XMLコメント<inheritdoc/>の使い方

5019 ワード
VisualStudio2019 VisualStudio2019 テキストリンク

このドキュメントの内容

VisualStudio2019 16.4 で inheritdoc がサポートされるようになりました。
メソッドをオーバーライドしたり、インターフェースのメンバを実装したりしたときに XML コメントを引き継ぐことができるようになる機能です。

対象のメソッドが複数の型パラメータや複数の引数を持つ場合にパラメータのコメントを期待通りに引き継がせることができず、小一時間試行錯誤してしまいました。単純な勘違いでした。

基底クラスに対してXMLコメントを記述する

次のように基底クラスを実装し、XMLコメントを記述しました。
GetItem メソッドは TKey, TItem の二つの型パラメータを持ちます。

/// <summary>
/// 基底クラス
/// </summary>
abstract class BaseClass
{
    /// <summary>
    /// 指定されたキーに対応するアイテムを取得します。
    /// </summary>
    /// <typeparam name="TKey">キーの型</typeparam>
    /// <typeparam name="TItem">アイテムの型</typeparam>
    /// <param name="key">キー</param>
    /// <param name="item">取得されたアイテム</param>
    /// <returns>取得できた場合 true を返します。</returns>
    /// <exception cref="KeyNotFoundException">
    /// 指定されたキーが存在しません。
    /// </exception>
    public abstract TItem GetItem<TKey, TItem>(TKey key);
}

誤）各タグに inheritdoc を記述する

summay や typeparam など各タグに inheritdoc を記述してみます。
基底クラスに記述したコメントは引き継がれるものの、型パラメータは全ての型パラメータに対するコメントが連結されて表示されてしまいます。

/// <summary>
/// サブクラス
/// </summary>
class SubClass : BaseClass
{
    /// <summary>
    /// <inheritdoc/>
    /// </summary>
    /// <typeparam name="TKey"><inheritdoc/></typeparam>
    /// <typeparam name="TItem"><inheritdoc/></typeparam>
    /// <param name="key"><inheritdoc/></param>
    /// <returns><inheritdoc/></returns>
    public override TItem GetItem<TKey, TItem>(TKey key)
    {
        return default;
    }
}

TKey のツールチップの表示結果です。TKey と TItem に対するコメントが連結された結果が表示されています。TItem のツールチップも同じです。

正）inheritdoc だけ記述する

/// <summary>
/// サブクラス
/// </summary>
class SubClass : BaseClass
{
    /// <inheritdoc/>
    public override TItem GetItem<TKey, TItem>(TKey key)
    {
        return default;
    }
}

Tkey のツールチップの表示結果です。TKey に対するコメントだけが表示されています。