Doxygen の特殊コマンドの typo チェックをする

ソースコードのドキュメント生成に Doxygen はよく使われていると思います。

/**
 * @ingroup VALUE_PARAMETERIZED_TEST
 * @def     IUTEST_INSTANTIATE_TEST_CASE_P
 * @brief   パラメータテストインスタンス化マクロ
 * @param   prefix_         = インスタンス名
 * @param   testfixture_    = テストフィクスチャ
 * @param   generator_      = Range, Bool, Values, ValuesIn, Combine, Pairwise ...
 * @param   ...             = Param name generator function (option)
*/

このようなコメントを記述することで自動的にドキュメントを生成する仕組みですが、
この @ から始まる特殊コマンドをよく typo してしまうことがあるので CI で簡単にチェックできるようにしてみました。

チェック用の .mk がこちら

make -C DoxygenCommandCheck.mk ROOT=path/to/dir

のように使用します。

自作の C++ テスティングフレームワークの iutest で実際に検出した結果がこちら。



やっぱり typo してましたね…
生成されたドキュメントを見ても、気づきにくいところだと思うので是非活用してみてください。
（しかし、なんで make で書いたんだろ… .sh で良かったのでは…）

[Doxygen] 必ずインクルード的なことをしてみた

Doxygen で必ずインクルード的なオプションってないの？

ないっぽい。

ので、回避策。

INPUT_FILTER を使う

Doxygen のオプションに INPUT_FILTER というものがあり、これを利用して実現しました。

Doxygen 設定

INPUT_FILTER タグでは、各入力ファイルをフィルタリングするのに使うプログラムを指定します。doxygen は、フィルタープログラムを起動するために、次のコマンドを (popen() を介して) 実行します。

<filter> <input-file>
ここで、<filter> は、INPUT_FILTER タグの値です。 また、<input-file> は、入力ファイルの名前です。 doxygen は、その後、フィルタープログラムが標準出力に書き出した出力を使用します。

今回用意したフィルタープログラムは python で以下のように書きました。

import sys

def main():
    f = open(sys.argv[1])
    n = 0
    if f:
        for line in f:
            sys.stdout.write(line)
            if line.find("//=========================================================") != -1:
                n += 1;
                if n == 2:
                    print('#include "iutest_config.hpp"')
    f.close()

if __name__ == '__main__':
    main()

ファイルの先頭にある Doxygen コメントの直後に「必ずインクルードしたいファイル」のインクルードディレクティブを挿入しているだけです。
先頭のコメントを読み飛ばす方法は、もっと汎用性あるやり方にもできますが、今回は iutest でのみ使えればよかったので簡単に済ませました。

必ずインクルードができたことで…

iutest では iutest.hpp ヘッダーファイルをインクルードして使うことを想定しています。
そのため、#include も端折れるところは端折ってます。
なので、include/*.hpp の別のファイルを"それだけで"インクルードしても、#include が足らずに使えなかったりします。

Doxygen はファイル個別に評価されるため、同様に #include が足りない状態で解析がされてしまいます。
そうするとマクロ定義がなかったりして、#if/#endif ブロックが有効にならずにドキュメント化されない、というのが問題になってました。
今回、「必ずインクルード」ができるようになったことで、このようなファイルの解析が期待通りにできるようになりました。


設定ファイルで指定できたら一番いいんですけどね。
今回は以上。