inheritdocを調査する

はじめに

Visual Studio 2019 version 16.4 Release Notes によると, 継承関係にあるクラスやメソッドには, 親のコメントを引き継いでクイック情報窓に表示するようになりました. inheritdocタグで明示することもできます. inheritdocタグを明示した場合, 警告CS1591は出力されません.
また, 16.4より前のリリースと出力されるXMLドキュメントは変わりません. いつからかはわかりませんが, inheritdocタグの補完がされるようになりました (Visual Studio 2017では候補にでない).

ここから, コメントからドキュメントを生成することに興味のない方には関係がありません.

inheritdocタグに対応, だけ見て"16.4より前だから対応していないらしい, コメントもそのままコピーしよう", とならない方がよいでしょう.

Sandcastle

Sandcastleは, C#コンパイラが生成したXMLからドキュメントを生成するシステムのひとつです.
継承先にコメントがない場合は取り込む, ある場合はリンク先を見てね, のような動作をするようです. コメントから直接イメージできるドキュメントにはならない印象です.

namespace Inheritdoc
{
    /// <summary>
    /// Something
    /// </summary>
    public interface ITweetAlert
    {
        /// <summary>
        /// This method does something0
        /// </summary>
        void Method0();

        /// <summary>
        /// This method does something1
        /// </summary>
        void Method1();
    }

    /// <inheritdoc />
    public class TweetAlert : ITweetAlert
    {
        public virtual void Method0()
        {
        }

        /// <inheritdoc />
        /// <summary>
        /// TweetAlert implements Method1
        /// </summary>
        public virtual void Method1()
        {
        }
    }
}

Javadoc

何も考えなくても美しいドキュメントが生成される印象です.

/**
 * Something
 */
interface ITweetAlert
{
    /**
     * This method does something0
     */
    public abstract void Method0();

    /**
     * This method does something1
     */
    public abstract void Method1();
}

class TweetAlert implements  ITweetAlert
{
    @Override
    public void Method0()
    {
    }

    /**
     * {@inheritDoc}
     * TweetAlert implements Method1
     */
    @Override
    public void Method1()
    {
    }
}

Javadocは継承先にコメントがない場合, 親のコメントを継承しますが, 注釈をつけてくれます.

    Method0

    public void Method0()

    インタフェースからコピーされた説明: ITweetAlert
    This method does something0

    定義:
        Method0 インタフェース内 ITweetAlert

    Method1

    public void Method1()

    This method does something1 TweetAlert implements Method1

    定義:
        Method1 インタフェース内 ITweetAlert

Doxygen

Doxygenでは, 設定 INHERIT_DOCSをYESにすると, メソッドのコメントを親から引き継ぎます, クラスのコメントは引き継ぎません. デフォルトでは, コメントのない要素のドキュメントは生成しなかったりと設定を細かく行う必要があります.
copydocコマンドで明示することもできます. copydocにメソッドを指定する場合, オーバーロード解決のために引数リストも指定します.

/**
@brief Something
*/
class ITweetAlert
{
public:
    /**
    @brief This method does something0
    */
    virtual void Method0() =0;
    /**
    @brief This method does something1
    */
    virtual void Method1() =0;
};

/**
@copydoc ITweetAlert
*/
class TweetAlert : public ITweetAlert
{
public:
    virtual void Method0() override
    {
    }
    /**
    @copydoc ITweetAlert::Method1()
    TweetAlert implements Method1
    */
    virtual void Method1() override
    {
    }
};

TweetAlert::Method1()のドキュメントは次のようになります. copydocコマンドでコピーしたドキュメントの次に, ピリオドが追加されます. 理由は不明です.

This method does something1.
TweetAlert implements Method1
Implements ITweetAlert.

まとめ

コメントからドキュメントを生成するシステムのほとんどは, 継承も考慮して設計されています.
オーバーライドしているかはナウい言語ではコードに書くことができますから, タグを明示的に書くかどうかは好みだと思います. 実装側にコメントを書かなければならないとしたら, 設計ミスの匂いがしますし.
コメントを書き忘れたのかな？と, 読み手に迷わせないために明示することが, 必要かもしれません.
複数個所に同じコメントを書くことはやめましょう.