[Doxygen] ドキュメント化していないコードの警告を抑制する

2023-12-22 (金)

Doxygen でドキュメントに出力対象ではない C# メソッドにおいて、警告メッセージが表示されていました。
WARN_AS_ERROR を YES にすると、警告がエラーとして扱われてしまうため、該当部分のコードを Doyxgen から除外させることで警告を回避しました。

環境

  • Doxygen 1.9.6
  • Windows 11 Pro 22H2 22621.2861
  • C# 12.0

結果

@cond@endcond で囲むことで、ドキュメント対象から除外します。
正確には警告の抑制ではなく、ドキュメントから除外します。

@cond に定義した任意のラベル名 DOXYGEN_SKIP は、本来 ENABLED_SECTIONS に定義することでドキュメント対象にするかどうかを制御できます。この機能を利用します。

// @cond DOXYGEN_SKIP

public (int X, int Y) Get()
{
    return default;
}

// @endcond

説明

WARN_IF_UNDOCUMENTED というオプションもあるようです。
EXTRACT_ALL を YES, NO どちらも組み合わせて試しましたが、本環境では警告が抑制できませんでした。

また、ドキュメントに出力させたいが、警告のみ抑制するのも可能のようです。
https://stackoverflow.com/questions/3506415/suppressing-doxygen-warnings
https://stackoverflow.com/questions/16993250/suppress-doxygen-warning-for-undocumented-member-function-but-leave-synopsis-in

//! @cond//! \{ で囲むようです。

しかし、C# で試しましたが効果がないようでした。
https://github.com/doxygen/doxygen/issues/7359

//! @cond DOXYGEN_SKIP

public (int X, int Y) Get() => default;

// @endcond

//! \{

public (int X, int Y) Get() => default;

//! \}

今回は、C# のタプルが Doyxgen でサポートされていないため、警告が発生していました。
タプルを使用したコードもドキュメント化したい場合は、代わりに docfx などを検討した方が良さそうです。
https://github.com/doxygen/doxygen/issues/7633

感謝

2023-12-22 (金)