Doxygenで生成されるドキュメントにC言語のマクロ定義が出てこないことがあるのを調査

環境

最近の Doxygen を使用。

PS > doxygen.exe -V
1.9.2 (caa4e3de211fbbef2c3adf58a6bd4c86d0eb7cb8)
    with clang support 5.0.0.

現象

test.h はドキュメント生成するつもりのないファイル。

ただし、以下のようにコメント文に Markdown のコードブロックの開始に該当する記述がある。

test.h

/***********
 * ~~~
 ***********/

test.c は test.h をインクルードしている。

test.c

/*! @file */

/*!
 * comment
 */
#define AAA

#include "test.h"

/*!
 * comment
 */
#define BBB

Doxygen の設定は、プリプロセスを処理した方が良いと考えて INCLUDE_PATH を追加。他の設定はデフォルトのまま。

MyDoxyfile

INCLUDE_PATH = "test.h の配置されているディレクトリのパス"

Doxygen を実行すると、以下のように警告が出力される。

PS > doxygen.exe MyDoxyfile | Out-Null
test.c:13: warning: documentation for unknown define BBB found.

生成される HTML ファイルに BBB が無い。

原因の推測

https://github.com/doxygen/doxygen/blob/Release_1_9_2/src/pre.l の処理。

プリプロセスで test.c に test.h のインクルードを見つけて test.h の解析に切り替え。
test.h の解析で ~~~ の閉じが無いので SkipVerbatim のまま <<EOF>> に到達。
test.c に戻ってきても SkipVerbatim で解析が進み BBB の定義が正常に解析されない。

解析するファイルの切り替えには flex の yy_switch_to_buffer() を使用している。
flex のドキュメントには yy_switch_to_buffer() は開始状態を変更しないとの記述。

https://github.com/westes/flex/blob/v2.6.4/doc/flex.texi#L2041

Note also that switching input sources via either @code{yy_switch_to_buffer()} or @code{yywrap()} does @emph{not} change the start condition.

回避策１

Doxygen の設定 INCLUDE_PATH を使わない。

回避策２

インクルードの直後に ~~~ の閉じを入れる。

test_new.c

/*! @file */

/*!
 * comment
 */
#define AAA

#include "test.h"

/*
 * ~~~
 */

/*!
 * comment
 */
#define BBB

Doxygen を実行すると、警告は出力されない。

PS > doxygen.exe MyDoxyfile | Out-Null

生成される HTML ファイルに BBB がある。