Doxygen対応Cプログラムコメント記述例ご紹介

作成者：TZ

弊社でのC言語で開発を行うプロジェクトでは、ソフトウェア詳細設計書にDoxygenで出力したデータを用いるため、必要な情報を出力するためのコメント記述をしております。

今回は弊社で用いるタグコメントの書き方について紹介させて頂きます。

実際にはDoxygenのオプション設定などにより別の記述もございますので、詳しくはDoxygenのサイトを参照頂ければと思います。

Doxygen設定(doxyfile)

良く使う基本的な設定は以下となります。

OUTPUT_LANGUAGE = Japanese
RECURSIVE = YES
JAVADOC_AUTOBRIEF = YES
OPTIMIZE_OUTPUT_FOR_C = YES

はじめに

• Doxygenのコメントブロックを記述する場合

/**
 * ...各種コメント記述...
 */

 または

//! ...各種コメント記述...

• メンバ後にコメントを付与する場合

int i;   //!< ...各種コメント記述...

ファイルコメント

以下のフォーマットをファイルの先頭に記述します。この記述がない場合はDoxygenの出力対象になりません(EXTRACT_ALLに依存)

/**
 * GUI KEYPAD機能
 *
 * KEYPAD [10KEY/文字入力]を制御するGUIアプリケーション
 *
 * Pericallis Ver 1.x
 * Copyright (C) 2010-2012, RIGHTxLIGHT, all right reserved.
 *
 * @file
 * @attention 特になし
 * $Id: KeyPad.c 180 2012-01-05 05:54:14Z user-id $
 */
#include <stdint.h>

• 2行目: 要約説明として一覧で表示されます。@briefに該当しますが省略可能です。詳細の見出しになるので簡潔に機能名称などを記述します。
• 3行目: 空白行にて要約説明セクションを終了します。
• 4行目: 詳細説明を記述します。@descriptionに該当しますが省略可能です。
• 9行目: @file については内容の記載は必要ありませんが、このタグがないとDoxygenの出力対象とみなされませんので空でもいいので宣言します。
• 10行目: 注意事項などがあれば記述します。なければ省略可能とします。内容によっては@noteを用いても良いかもしれません。
• 11行目: subversionのタグとなります。必要に応じて登録します。

課題：Subversion等の構成管理ツールが出力するリビジョン、ID等の情報をDoxygenでの出力情報として流用できないか

マクロ定義、列挙体、構造体、変数定義

#define KEYPAD_OBJECT_MAX (20) //!< KEYPADオブジェクト数の最大値の定義

/**
 * 設定値入力"分類"定義
 */
typedef enum {
    INPUT_CLASS_INVALID,   //!< 分類なし
    INPUT_CLASS_SECOND,    //!< 秒"s"
    INPUT_CLASS_FREQUENCY, //!< 周波数"Hz"
    INPUT_CLASS_VOLTAGE,   //!< 電圧"V"
    INPUT_CLASS_AMPERE,    //!< 電流"A"
    INPUT_CLASS_OHM,       //!< 抵抗"Ω"
    INPUT_CLASS_DEG_C,     //!< 温度"DO"
    INPUT_CLASS_MAX,       //!< 最大値
} inputClass_t;

/**
 * GUIオブジェクト描画情報
 */
typedef struct {
    OBJ_ID objectID;       //!< オブジェクトID

    //! 描画サイズ情報
    struct {
        int16_t width;     //!< 幅
        int16_t height;    //!< 高さ
    } drawSize;
} guiObjectInfo_t;

/**
 * KEYPADオブジェクト情報
 */
guiObjectInfo_t guiObjectKeypad[KEYPAD_OBJECT_MAX];

関数ヘッダ

/**
 * メモリ領域をコピーする
 *
 * メモリ領域srtの先頭sizeバイトをメモリ領域dstへコピーする。
 * @param[out] dst コピー先のメモリ領域
 * @param[in] src コピー元のメモリ領域
 * @param[in] size コピーするバイト数
 * @return dstへのポインタ
 * @attention コピー先とコピー元の領域が重なる場合は
 *    memmoveを使用すること
 */
void* memcpy(void *restrict dst, const void *restrict src
        , size_t size)

• 2行目: 要約説明として一覧で表示されます。@briefに該当しますが省略可能です。
• 3行目: 空白行にて要約説明セクションを終了します。
• 4行目: 詳細説明を記述します。@descriptionに該当しますが省略可能です。
• 5～7行目: 引数の説明を記述します。入力は[in]、出力は[out]、入出力は[in,out]とします。原則的にポインタ以外は[in]、const修飾ポインタは[in]、const修飾なしポインタでは[out]または[in,out]となります。
• 8行目: 戻り値の説明を記述します。複数の説明を列挙したい場合は@retvalを用います。
• 9行目: 使用上の注意などがあれば記述します。特になければ省略可能とします。内容により@noteと使い分けると良いでしょう。