質問をすることでしか得られない、回答やアドバイスがある。

15分調べてもわからないことは、質問しよう!

ただいまの
回答率

90.35%

  • C

    4947questions

    C言語は、1972年にAT&Tベル研究所の、デニス・リッチーが主体となって作成したプログラミング言語です。 B言語の後継言語として開発されたことからC言語と命名。そのため、表記法などはB言語やALGOLに近いとされています。 Cの拡張版であるC++言語とともに、現在世界中でもっとも普及されているプログラミング言語です。

複数行に渡る関数形式マクロを使用してもdoxygenで正常にドキュメント出力したい

受付中

回答 1

投稿 編集

  • 評価
  • クリップ 0
  • VIEW 2,646

megane814

score 9

関数形式マクロを使用してもドキュメントをdoxygenで出力したい

Windows・Cygwin環境下にて、C言語で開発を行なっています。
詳細設計レベルのドキュメントに関してはdoxygenで出力することになっているのですが、少々困っています。

下記に紹介するような複数行に渡る関数形式マクロを使用すると、2つの問題が発生してしまいました。

  1. 未知の定義¥HOGE_MAXが定義される(doxygen warningの発生)
  2. 出力したHTMLドキュメントの関数mogeについて、static void moge ( int c, int d )の説明と、moge(x, MOO)の説明の、2つの説明が表示される
  3. 出力したHTMLドキュメントにHOGE_MAXの説明「影響を受ける記述」が表示されない

複数行に渡る関数形式マクロを使用しても、意図通りにdoxygenでドキュメントを出力するための方法はありますでしょうか。

該当のソースコード

static void hoge ( int a, int b );
static void moge ( int c, int d );

/**
 * @def FOO (-1)
 * 適当な説明
 */
#define FOO (-1)

/**
 * @def MOO (1)
 * 適当な説明
 */
#define MOO (1)

/**
 * @def Hoge(x)
 * 問題が発生する原因となるマクロ
 */
#define Hoge(x)   ¥
{                            ¥
    hoge(x, FOO);   ¥
    moge(x, MOO);  ¥
}

/**
 * @def HOGE_MAX (0xFF)
 * 影響を受ける記述
 */
#define HOGE_MAX (0xFF)

/**
 * @brief 適当な説明
 * 
 * @param[in] (a) 適当な説明
 * @param[in] (b) 適当な説明
 * @return -
 */
static void hoge ( int a, int b )
{}

/**
 * @brief 適当な説明
 * 
 * @param[in] (c) 適当な説明
 * @param[in] (d) 適当な説明
 * @return -
 */
static void moge ( int c, int d );
{}

 表示されたエラーメッセージ

Searching for documented defines...
hoge.c:12: warning: documentation for unknown define ¥HOGE_MAX found.

関数形式マクロの改行に使用した¥が後の@defに影響を与えているようです。

試したこと

 試したことその1

static void hoge ( int a, int b );
static void moge ( int c, int d );

/**
 * @def FOO
 * 適当な説明
 */
#define FOO (-1)

/**
 * @def MOO
 * 適当な説明
 */
#define MOO (1)

/**
 * @def Hoge(x)
 * 適当な説明
 */
#define Hoge(x)   ¥
{                            ¥
    hoge(x, FOO);   ¥
    moge(x, MOO);  ¥
}

/** @def */    /* <---- このコメントを追加 */

/**
 * @def HOGE_MAX (0xFF)
 * ほげ最大値
 */
#define HOGE_MAX (0xFF)

/**
 * @brief 適当な説明
 * 
 * @param[in] (a) 適当な説明
 * @param[in] (b) 適当な説明
 * @return -
 */
static void hoge ( int a, int b )
{}

/**
 * @brief 適当な説明
 * 
 * @param[in] (c) 適当な説明
 * @param[in] (d) 適当な説明
 * @return -
 */
static void moge ( int c, int d );
{}

コメント/** @def */を追加すると、ワーニングは消えました。
(問題点1は解消されました)
どういう作用によるものかはわかっていません。
(正しく書くなら/** * @def */だと思いますが、これでは解消されませんでした)
(@defの代わりに@fnでは解消されませんでした)
問題点2は解消されませんでした。
問題点3も解消されませんでした。

 試したことその2

回答で頂いたセミコロンを追加する案を試してみました。

static void hoge ( int a, int b );
static void moge ( int c, int d );

/**
 * @def FOO
 * 適当な説明
 */
#define FOO (-1)

/**
 * @def MOO
 * 適当な説明
 */
#define MOO (1)

/**
 * @def Hoge(x)
 * 適当な説明
 */
#define Hoge(x)   ¥
{                            ¥
    hoge(x, FOO);   ¥
    moge(x, MOO);  ¥
}

;    /* <---- このセミコロンを追加 */

/**
 * @def HOGE_MAX (0xFF)
 * ほげ最大値
 */
#define HOGE_MAX (0xFF)

/**
 * @brief 適当な説明
 * 
 * @param[in] (a) 適当な説明
 * @param[in] (b) 適当な説明
 * @return -
 */
static void hoge ( int a, int b )
{}

/**
 * @brief 適当な説明
 * 
 * @param[in] (c) 適当な説明
 * @param[in] (d) 適当な説明
 * @return -
 */
static void moge ( int c, int d );
{}

セミコロンを追加した場合、問題点1は解消されます。
しかし、代わりに、HTMLドキュメントに変数¥が出力されるようになってしましました。
また、問題点2、問題点3は解消されませんでした。

補足情報(言語/FW/ツール等のバージョンなど)

Windows
Cygwin
C言語

  • 気になる質問をクリップする

    クリップした質問は、後からいつでもマイページで確認できます。

    またクリップした質問に回答があった際、通知やメールを受け取ることができます。

    クリップを取り消します

  • 良い質問の評価を上げる

    以下のような質問は評価を上げましょう

    • 質問内容が明確
    • 自分も答えを知りたい
    • 質問者以外のユーザにも役立つ

    評価が高い質問は、TOPページの「注目」タブのフィードに表示されやすくなります。

    質問の評価を上げたことを取り消します

  • 評価を下げられる数の上限に達しました

    評価を下げることができません

    • 1日5回まで評価を下げられます
    • 1日に1ユーザに対して2回まで評価を下げられます

    質問の評価を下げる

    teratailでは下記のような質問を「具体的に困っていることがない質問」、「サイトポリシーに違反する質問」と定義し、推奨していません。

    • プログラミングに関係のない質問
    • やってほしいことだけを記載した丸投げの質問
    • 問題・課題が含まれていない質問
    • 意図的に内容が抹消された質問
    • 広告と受け取られるような投稿

    評価が下がると、TOPページの「アクティブ」「注目」タブのフィードに表示されにくくなります。

    質問の評価を下げたことを取り消します

    この機能は開放されていません

    評価を下げる条件を満たしてません

    評価を下げる理由を選択してください

    詳細な説明はこちら

    上記に当てはまらず、質問内容が明確になっていない質問には「情報の追加・修正依頼」機能からコメントをしてください。

    質問の評価を下げる機能の利用条件

    この機能を利用するためには、以下の事項を行う必要があります。

回答 1

+1

ちょっと今doxygenを動かせる環境にないのですが、関数形式のマクロを「@def」ではなく「@fn」にしてもダメなんでしょうか?


追記:
確かに、ダメですね。定義が逆の場合は出るのですが・・・。
「@fn」でも同じですね。
色々やってみましたがダメでした。
マクロの行分けに使っているバックスラッシュが悪さをしているのでしょうね。

オプションを色々探してみましたがそれらしいものが見当たりませんね。
解決になっておらずすいません。


再追記:
うまく出ましたよ!
以下のように、関数形式の複数行マクロと次の定義の間にセミコロン(;)を入れれば出るようになります。

/**
 * @def Hoge(x)
 * 適当な説明
 */
#define Hoge(x) ¥
{                          ¥
    (x+1)              ¥
}

;    /* <-- これを追加 */

/**
 * @def HOGE_MAX (0xFF)
 * ほげ最大値
 */
#define HOGE_MAX (0xFF)


セミコロンだけの行はC/C++では無視されるのでコンパイルエラーにもなりません。(VC++ではそう)
ところでこの関数形式のマクロですがこのままではエラーになりますね。(セミコロンがないので)

投稿

編集

  • 回答の評価を上げる

    以下のような回答は評価を上げましょう

    • 正しい回答
    • わかりやすい回答
    • ためになる回答

    評価が高い回答ほどページの上位に表示されます。

  • 回答の評価を下げる

    下記のような回答は推奨されていません。

    • 間違っている回答
    • 質問の回答になっていない投稿
    • スパムや攻撃的な表現を用いた投稿

    評価を下げる際はその理由を明確に伝え、適切な回答に修正してもらいましょう。

  • 2017/09/15 17:04

    確かに「変数\」が出てますね。
    どうも、難しいのかもしれません。セミコロンを思いついたのは、doxygenの説明を読んでいて、セミコロンなしでマクロを使っているとおかしくなるようなことが書いてあったので、よもやと思ってやってみました。
    となると、doxygenの開発している人に直接質問を投げてみないと難しいかもしれません。

    キャンセル

  • 2017/09/17 15:39

    ですかー……。
    引き続き回答を募集しつつ、doxygenの中の人にコンタクト、取ってみようかと思います。
    日本語で質問できると良いのですが……。

    キャンセル

  • 2017/09/21 17:13

    free.mlに日本語のメーリングリストがありますね。
    まずはここで聞いてみるのが良いかもしれません。
    http://www.freeml.com/doxygen

    本家は英語なので↓です。
    https://sourceforge.net/p/doxygen/mailman/

    以前TortoiseSVNの英語のメーリングリストに質問したことが有ります。Google翻訳を使って四苦八苦しながら書いてました。(その時は切実だったので)
    Google翻訳を使って投げればそれなりの返事は返ってくると思います。

    キャンセル

15分調べてもわからないことは、teratailで質問しよう!

  • ただいまの回答率 90.35%
  • 質問をまとめることで、思考を整理して素早く解決
  • テンプレート機能で、簡単に質問をまとめられる

同じタグがついた質問を見る

  • C

    4947questions

    C言語は、1972年にAT&Tベル研究所の、デニス・リッチーが主体となって作成したプログラミング言語です。 B言語の後継言語として開発されたことからC言語と命名。そのため、表記法などはB言語やALGOLに近いとされています。 Cの拡張版であるC++言語とともに、現在世界中でもっとも普及されているプログラミング言語です。

  • トップ
  • Cに関する質問
  • 複数行に渡る関数形式マクロを使用してもdoxygenで正常にドキュメント出力したい