#doxygen

[insightfactory]

Good looking documentation on BEntry::Exists().

[notsogreeeen]

Who was gonna tell me doxygen existed??

Who??

I am become doxygen stan until I learn of something better.

[ians-wiki]

Doxygen Primer

By Ian Elsbree, 2022-09-19

Table of Contents

Doxygen Primer

Table of Contents

Introduction

Doxygen

Doxygen Comments

Doxyfiles

Using Someone Else's Doxyfile

Turning LaTeX into PDF

Conclusion

Introduction

Welcome to the Doxygen Primer! This document is meant to get you up to speed on Doxygen, a documentation generator that makes it easy to document your code. This primer is not an in-depth usage guide, nor a complete documentation, nor an exhaustive list of features. It is only a basic introduction to the usage of Doxygen, primarily written for use in the CS-120, CS-170, and CS-180 courses. Of course, this document will apply to other uses, but its scope is limited intentionally. With that said, let's see what all the fuss is about.

Doxygen

Doxygen is a program. It runs when you run the command doxygen. It expects something called a doxyfile (explained later) to be in the current working directory, named Doxyfile.

Here is the official Doxygen Manual.

Doxygen's purpose is to scan source code files, in this context .c or .cpp (or .h) files, and generate documentation on the code within them, so that other programmers can more easily understand the purpose of your code and how to use it. It does this by generating files in either HTML format or LaTeX format (or both), which you can then use either as an HTML webpage, or use another tool such as pdf-latex to generate a PDF file from the LaTeX files. Either of these options will result in a document which explains how your code works to the reader.

Doxygen is not complicated to use in a simple use case. Most basically, you only have to run the command doxygen -g to generate a default configuration file, and then run the command doxygen to create the documentation for your code. However, there is some more information which will be useful to know about.

Doxygen Comments

Doxygen scans the comments in your source code. To make Doxygen aware of the information it needs to generate the documentation, you need to use special comments. You will need to put a Doxygen comment at the top of your file (a file header), specifying information about the file, as well as comments above each of your functions (function headers), specifying information about each of them. Here is an example Doxygen-style comment (this one is for a function):

/** * @brief Dynamically allocates a new node, initializing it with data. * * @param value The value to store in the node * @param label The label to associate with the node * @return A pointer to the newly made node */

Okay, what do we see here? A few things:

Doxygen comments begin with an extra * symbol, so you get /** instead of the normal /*.

The asterisks at the beginning of each line are optional. They just look nice.

Each line contains what's called a tag, followed by information.

Tags start with either a @ or a \ (either one works).

Tags denote some kind of information that would be useful to have in the documentation of your code.

The name of the tag determines how it is used in the documentation.

The information after the tag is displayed in the documentation.

Doxygen comments end like normal comments.

The most notable tags you will use are:

@file - Used as the name of the file the code is in.

@author - Used to credit the author of the file.

@date - Used to record the date of authorship of the file, or, in the case of the CS courses I mentioned earlier, the due date of the assignment.

@par - Used to display any information that does not have its own tag. If you use this tag and place a field name, and the field value on the following line, it will be displayed in the same way the author and date tags are.

@brief - Used to give a short description to a file or a function.

@param - Used to give the parameters of a function. The first word after the tag is the name of the parameter, and everything after that is the description of the parameter.

@return - Used to give the return value of a function.

There are other tags, although they are not as frequent, depending on the type of programming you do. Refer to the official manual for more information.

Doxyfiles

When you run Doxygen, it looks for a configuration file called a doxyfile. The default name it will look for is Doxyfile, with no file extension. A doxyfile is a text file, much in the same way that a C source code file is a text file. If you look at the default doxyfile (generated with the command doxygen -g), you can see the structure of a doxyfile, with options, followed by =, followed by values.

Notable options include:

PROJECT_NAME - The title of your documentation. Be sure to change this.

GENERATE_LATEX and GENERATE_HTML - Select what kind of documentation files to generate.

There are many, many more options available, although these are the most critical. Again, refer to the official manual for more information.

Using Someone Else's Doxyfile

If someone such as your professor provides a file named Doxyfile, good news! You don't have to configure one yourself. However, this is very important: make sure you edit the doxyfile to change the PROJECT_NAME to something suitable.

Other than that, using someone else's doxyfile is as simple as putting it the directory of your project and running the command doxygen. That's it. You should see a new folder or two, depending on what type of documentation you're generating. Inside these folders is your fresh, hot-off-the-press documentation. Have fun!

Turning LaTeX into PDF

You may have generated LaTeX documentation, but to view that, you'll need a program that can render LaTeX markup. Instead, you can generate a PDF document that more people's computers will be able to display easily.

Inside of the latex folder that was generated, you'll see a makefile, intended for the program make. Surprise! I have a primer on make and makefiles here. But for this usage, you should only need to run the commands cd latex to get into the latex directory and make to generate a PDF of your documentation. You will need a command called pdflatex for the makefile to work properly, which can be gotten as part of a package set called texlive.

After you run make, you'll see a file called refman.pdf is generated. That file is a PDF document that contains the full documentation for your project. Congratulations! Doesn't it look pretty?

Conclusion

You should now have some introductory knowledge of how to use Doxygen effectively. If you feel there is anything this document did not cover that you think it should, or anything you're left wondering after reading, or anything I can improve, please let me know! My goal is for this document to be easily read and comprehended, and to give you all the knowledge you need to be a more effective developer.

Created: 2022-09-19 Last Updated: 2022-11-09 © 2022 Ian Elsbree

[mits-whisper-blog]

Ｃプログラマのためのdoxygen

doxygenとは、ソースコード内に含まれる規定の形式のコメント(doxygenコメント)から、ドキュメントを自動生成してくれるシステムである。 doxygenでは各種プログラム言語がサポートされているが、ここではＣプログラム中心に話しを進めている。

自分は普段Ｃでプログラムを書いているが、doxygenコメントについて備忘録的なものが欲しいと思いまとめてみた。 そういった経緯があるので、このまとめは少し情報に片寄りがあると思う。

このまとめでは doxygen 1.8.9.1 をベースにしており、自分の環境(Mac OS X)での表示をサンプルとして挙げている。 出力結果の文言が変わったりするだろうが、他の環境でもそれほど大きな違いはないだろう。

doxygenは数多くの設定を持つが、自分はほとんどデフォルトのままで使用している。しかし、使うに当たって調整した方が良いものもある。 そのような設定に関しては、[7] インストール時に設定したものとしてまとめておいた。

目次

[1] 単なるＣプログラムをdoxygenにかける

[2] doxygenコメント

[3] 改行

[4] 箇条書きと連番リスト

[5] Markdown記法

[6] doxygenコマンド

[6-1] 総合概要(メインページ)と諸情報

@mainpage, @page, @section, @subsection, @par

[6-2] ファイルヘッダと変更履歴

@file, @brief, @author, @date, @version, @copyright, @par

[6-3] 関数ヘッダ

@brief, @param, @retval, @return

[6-4] 関数の事前条件と事後条件

@pre, @post

[6-5] 関数などの自動リンク

@sa

[6-6] 注意、警告、バグ、todo

@remarks, @attension, @warning, @bug, @note, @todo

[7] インストール時に設定したもの

参考URL

本家(英語): http://www.doxygen.org/

日本語版: http://www.doxygen.jp/

日本語で非常に助かるが、残念ながら対象バージョンが古い。

Graphviz: http://graphviz.org/

図形描画パッケージ。doxygenから使う。

[1] 単なるＣプログラムをdoxygenにかける

doxygenは、ソースプログラムに含まれている特殊な形式のコメント(doxygenコメント)をもとに、ドキュメントを自動生成してくれるシステムだが、doxygen形式のコメントが入ってない普通のＣのプログラムを入力しても、それなりの出力をしてくれる。

以下のようなファイル(hello.c)の先頭に/** @file 〜 **/の行だけを入れてみてdoxygenにかけてみる。

/** @file hello.c **/ #include <stdio.h> const char greeting[] = "Hello, World"; int main(int argc, char **argv) { puts(greeting); return 0; }

先頭ページで「ファイル」というタブをクリックすると以下のような表示になる。「hello.c」がリンクになっている。

出力例：

「hello.c」をクリックすると以下のような表示になる。

出力例：

このように、includeファイルの依存関係や、定義されている関数、変数などの一覧をちゃんと解析して出力してくれる。(ここには無いが、マクロ、構造体、列挙型もあれば解析して出力してくれる。)

残念ながら、それ以上の情報は出てこないが、それでもただのＣプログラムから、これだけの情報を抽出してくれる。

この出力に肉付けしていくのがdoxygenコメントとなる。

ちなみに、Ｃプログラムでは、ここで示した/** @file 〜 **/の行は必須である。また、ファイル名も必ず一致してなければならない。これを間違うと何も有用な出力が成されない。

☞目次へ戻る。

[2] doxygenコメント

doxygenコメントは以下の四つの形式がある。

① /** ～ */ ② /*! ～ */ ③ /// ～ ④ //! ～

原則的に、これらは書き方が異なるだけで大きな違いはない(微妙な違いについては、あとで触れる)。 例えば①の形式ならば、/**の部分がキーとなるようで、以下のように色々な記述の仕方ができる。

/** バッファの説明 */ unsigned char Buf[1024];

/** バッファの説明 **/ /*** これはdoxygenコメントではないでの無視される ***/ unsigned char Buf[1024];

/** * バッファの説明 */ unsigned char Buf[1024];

/** バッファの説明 */ unsigned char Buf[1024];

/*************************************//** * バッファの説明 ******************************************/ unsigned char Buf[1024];

最後の例は、通常のコメント/*****...*/の後ろから①のコメントが始まっている形式だ。 これらは、すべて同じ出力になる。

出力例：

さらに、①〜④のコメントの左端に<を付けることにより、行の後ろにdoxygenコメントを置くことができる。

①' /**< ～ */ ②' /*!< ～ */ ③' ///< ～ ④' //!< ～

先の例を使って示すと、以下のようになる。これも同じものが出力される。

unsigned char Buf[1024]; /**< バッファの説明 */

ちなみに、①と②(/*で始まる)、③と④(//で始まる)は、お互いに同じ出力となるが、①、②系と③、④系の出力は微妙に異なるようだ。

unsigned char Buf1[1024]; /**< ①、②系バッファの説明 */ unsigned char Buf2[1024]; ///< ③、④系バッファの説明

出力例：

①、②系は変数詳解が別に設けられて表示されるようであり、「変数」欄の「Buf1」がリンクになっており、「変数詳解」欄に飛ぶようになっている。 ③、④系は変数欄にまとまって出力される。 これらは、好みに応じて使い分ければ良いだろう。

ちなみに①'～④'の形式は、どちらかというと構造体のメンバ説明や、列挙型の項目説明で使うのが本来の用途なのだろう。

/** 解析の状態値 **/ enum CommandSta { IDLE, /**< アイドル **/ ACT, /**< 稼働 **/ SLEEP, /**< 停止中 **/ };

出力例：

/** 解析の状態値 **/は①形式のdoxygenコメントであるので、「列挙型詳解」欄に出力されている。 これを/*** 解析の状態値 ***/などとしては出力されなくなる。

☞目次へ戻る

[3] 改行

doxygenコメント内の文章は、実際の改行位置とは無関係に、詰めるだけ詰めて表示される。 明示的に改行したい場合は、何も無い空のコメント行を挟む必要がある。 以下に例を示す。

/** * 単純な改行は * 詰めるだけ詰めて表示される。 * 明示的に改行したい場合は、以下のように * * 空のコメント行を挟む。 */ void dummy(void) { /* 何もしない */ }

出力例：

コメントブロック内の各行を*で始めているので、この文字列だけの行(スペースやタブは無視されるようだ)があれば、そこが段落の区切りとなり、改行されて出力される。以降、このような空のコメント行のことを、単に「空行」と呼ぶ。

doxygenは最終的にHTMLに翻訳されるため、HTMLでおなじみの<br>タグでも改行できる。また、doxygenコマンド自体に「改行」を意味する\nや@nといったコマンドがあるので、これらを入力しても改行できる。

以下の例では、この他にHTMLタグである<b>タグを使用している。

/** * <b>タイトル</b><br> * ・最初の説明<br> * ・ニ番目の説明\n * ・三番目の説明@n * ・四番目の説明 */ void dummy(void) { /* 何もしない */ }

出力例：

なお、上のようなケースでは「[4] 箇条書きと連番リスト」で説明する「箇条書き」を使った方が、もっとスマートに記述できる。

/** * タイトル * * - 最初の説明 * - ニ番目の説明 * - 三番目の説明 * - 四番目の説明 */ void dummy(void) { /* 何もしない */ }

出力例：

ところで、MacOS Xでバックスラッシュ「＼」を入力する時には注意が必要である。 Mac OS Xでは、半角の円記号「￥(0xa5)」と半角のバックスラッシュ「＼(0x5c)」が明確に区別されており、キーボードの「￥」キーを押した時にどちらが入力されるかは「システム環境設定」に依存する。

試しに「￥」キーを押した時に「￥」が表示されたら、それは円記号「￥(0xa5)」でありバックスラッシュ「＼(0x5c)」ではない。だから「￥ｎ」と入力しても改行されない。この場合は、Optionキーを押しながら「￥」キーを押すと良い。 デフォルトでバックスラッシュを入力したいと思ったら「システム環境設定」での変更が必要だ。

日本語版Windowsでは、この点がうまく隠されており、「￥」キーを押した時は「＼(0x5c)」が入力される。さらに、日本語フォントの場合はバックスラッシュ「＼(0x5c)」を「￥」と表示する。だから「￥ｎ」と表示されていても、ちゃんと改行されるのだ。

ちなみに、上記の例のように、コメントの中にやたら<b>や<br>などのHTMLタグが入っているコードを見ることがあるが、あれは何だろう。 ひどいものになると、偏執狂的に各行、各行に<br>が付いていたり、お飾りのためのHTMLタグも入っていたりする。

そのHTMLタグはdoxygenの整形プログラムを通らないとまともに見られないわけで、普通にソースコードリーディングしている分には目障りで見苦しいばかりなのに。 doxygenコメントに凝るのも良いが、普段は普通に読めて、doxygenに通せば、より綺麗に読めるコメントの書き方をするのが本筋だと思うのだが。

何か途中から全然doxygenの説明になってませんね。

☞目次へ戻る

[4] 箇条書きと連番リスト

doxygenコメント内に、-や-#で始まる行を記述すると、箇条書きや連番リストとして出力される。

-とスペースで「箇条書き」となる。タブやスペースで段付けすると、より低いレベルの箇条書きを示すことができる。 また、.のみの行は、そのレベルの箇条書きを終了させる。

/** * タイトル * * - 箇条書き1 * - 箇条書き2 * - 箇条書き2-1 * この行は上の行に詰めさせられる。 * - 箇条書き2-1-1 * . * 箇条書き2-1の追加説明 * - 箇条書き2-2 * - 箇条書き3 */ void dummy(void) { /* 何もしない */ }

出力例：

上の例の通り、隣接する行は詰めるだけ詰めて出力されるので、これが嫌な場合は、同じレベルにドット(.)だけを置くことにより、その前の箇条書きを終わらせることができる(箇条書き2-1-1の後の.のみのコメント行がそれだ)。

先頭を-#で始めると連番リストになる。

/** * タイトル * * -# 連番リスト1 * -# 連番リスト2 * -# 連番リスト2-1 * -# 連番リスト2-2 * - さらに箇条書きを含めることも可能。 * このように別の行に書いても詰めさせられる。 * . * . * 同じレベルにドットをおくことで該当のレベルを強制的に * 終わらせる。 * -# 連番リスト3 * . * -# 連番リスト(新しい1) */ void dummy(void) { /* 何もしない */ }

出力例：

「連番リスト3」の後に.だけの行がある。これで次からは新しい連番リストとなる。

普通にソースコードリーディングしている場合は、-はまだしも、-#は単なる変な記号にしか見えない。doxygen 1.8.0からは、Markdownと同じく1.や2.という連番リストが振れるようになった。 Markdownサポートに関しては次の項で説明する。

☞目次へ戻る

[5] Markdown記法

doxygen 1.8.0 からはMarkdown記法もサポートされるようになった。

Markdownのような箇条書き、連番リスト、表、水平線、その他の記述ができるようになった。 以下に例を示す。

/** * ### タイトル * * この関数の機能 * _ _ _ * 1. メイン機能 * * 説明1 * * 説明2 * 2. サブ機能 * 1. サブ機能1 * 2. サブ機能2 * * | 左詰め | 中央揃え | 右詰め | * |:------ |:--------:| ------:| * | 1-1 | 1-2 | 1-3 | * | 2-1 | 2-2 | 2-3 | */ void dummy(void) { /* 何もしない */ }

出力例：

「###」はMarkdownのタイトル指定(H3を使用)、「_ _ _」は水平線だ。

オリジナルのMarkdown記法の他に、いくつかの有名な拡張機能もサポートされているようなので、参考までに以下にURLを貼り付けておく。

Doxygen Markdown support

URL: http://www.stack.nl/~dimitri/doxygen/manual/markdown.html

なお、残念ながら「行末にスペースを二つ以上入れての改行」での「強制改行」はサポートされていないようだ。 やっぱり互換性とかに問題があるのだろうか。

☞目次へ戻る

[6] doxygenコマンド

doxygenコメントの中に、\や@で始まる特殊コマンドを挟み込むことにより、色々な情報を付加して出力することが可能となる。 これ以降は、そのような特殊コマンドについて、目的別に説明して行こう。

なお、ここでは特殊コマンドを@形式で記述するが、これは単純に自分の好みである。 例えば、@briefは\briefと記述しても良いので、好みの方を選べば良いだろう。

☞目次へ戻る

[6-1] 総合概要(メインページ)と諸情報

doxygenで作ったドキュメントで一番最初に表示されるページ(「総合概要」、又は「メインページ」)があるが、そのままだと、ここには何も表示されず、ちょっと格好悪い。

このページに載せたい文書はdoxygenコマンドの@mainpageコマンドで作ることができる。 また、@pageコマンドを使えば、他のページを作ることもできる。 以下にこれらの例を示す。

/** * @mainpage メインタイトル * いろいろな説明 * * @section main_sec 大項目 * 大項目の説明 * * @subsection main_subsec 中項目 * 中項目の説明 * * @par 小項目 * 詳しくは @ref more_info も参照のこと。 */ /** * @page more_info 補足説明 * 色々な補足の説明。 * 大本の @ref main_sec も参照のこと。 */ /** * @page more_info2 さらなる補足説明 * さらに色々な補足の説明。 */

これらのコメントは、同じファイルに記述しても良いし、別々のファイルに記述しても良い。 @mainpageに記述したコメントが最初のページ(「総合概要」、又は「メインページ」)に表示される。

出力例：最初のページ(総合概要、又はメインページ)

上記例の「小項目」中にある補足説明はリンクになっている。これは@refコマンドの結果だ。

@pageに記述したコメントが「諸情報」ページに表示される。

出力例：@pageで作ったページ(諸情報)

この例での補足説明と、さらなる補足説明は全てリンクになっている。 クリックすると以下のようなページが表示される。

出力例：補足説明

出力例：さらなる補足説明

「補足説明」のページの大項目の部分も@refコマンドで作ったリンクになっている。

@section、@subsection、@page各コマンドの左のmain_sec、main_subsec、more_info、more_info2は、全て@refコマンドでのリンク先に使う。クリックすると、それぞれ該当のページを表示する。

なお、@refコマンドでリンクを張る場合は、上記例のように、名前の前後にスペースが必要である。スペース無しで前後に詰めて書いてしまうとリンクとして認識されなくなる。

☞目次へ戻る

[6-2] ファイルヘッダと変更履歴

プログラムファイルの先頭には、そのファイル自体の説明や変更履歴などを記述すると思う。

それらの情報を見栄えよく出力してくれるdoxygenコマンドがある。 以下にその例を示す。

/** * @file RingBuf.c * @brief リングバッファライブラリ * * 一般的なリングバッファ制御のためのAPIをまとめたライブラリ。 * * @author mits * @date 2015.01.20 * @version 1.0 * @copyright 2015 Mits Corp. All rights reserved. * * @par 変更履歴: * - 2015.01.15: mits: 新規作成 * - 2015.01.20: mits: 以下の通り * 1. 空きバッファサイズの計算方法がおかしかったので直す。 * 2. 関数名のリファクタリングを行った。 * - Command* → Cm_* * - Driver* → D_* */

まず、「ファイル」ページにファイルの一覧が表示される。

出力例：

ファイル名の脇に表示されているメッセージは@briefコマンドで記述したものである。 このファイル名(例ではRingBuf.c)はリンクになっている。

ファイル名をクリックすると、doxygenコメントで書いた情報が表示される。

出力例：

項目 コマンド 説明 ファイル名 @file ファイル名を示す。必須項目であり、これが無いとＣプログラムでは、まともにページを作ってくれない。 また、ここで記述するファイル名は、実際のファイル名と一致してなければならない。 概要 @brief 本ファイルの概要説明。ファイル一覧ページでは、この概要説明が使われる。 なお、上記例のように、@briefのあとに空行を一行挟んだ後、詳しい説明を書くのが一般的だ。 作者、日付け、バージョン、著作権 @author, @date, @version, @copyright いつもの記述。お好みでどうぞ。 段落 @par @parコマンドは、別に変更履歴用のコマンドではないが、このようにまとまった文章を書くために重宝するので使っている。 この例で示したように、複数の情報を列挙するには「箇条書き」や「連番リスト」が非常に重宝する。わざわざ見苦しく<br>を乱発しなくても済む。

☞目次へ戻る

[6-3] 関数ヘッダ

関数定義の前に、その関数の処理内容や引数、戻り値などの説明を書いたりするが、それらを見栄えよく出力してくれるdoxygenコマンドについて説明する。 以下に例を示す。

/** * @brief 概要説明 * * その簡単な説明。 * * @param[out] op 出力パラメータ * @param[in] ip 入力パラメータ * @param[in,out] iop 入出力パラメータ * @retval true 処理成功。 * @retval false 処理失敗。 */ bool dummy(char *op, int ip, int *iop) { /* 略 */ }

出力例：

関数の戻り値を示すdoxygenコマンドとしては、他に@returnもある。

/** 〜 略 〜 * @return 0～MAX_BUFの範囲値を返す。 〜 略 〜 */

出力例：

項目 コマンド 説明 概要 @brief ファイルヘッダでも使った@briefコマンドだ。関数一覧には、ここで記述した文章が出力される。 ファイルヘッダ同様に、空行を一行挟んだ後、説明を書くのが一般的だ。 引数 @param 関数の引数は、このコマンドで指定する。 この例のように、各引数には出力・入力・入出力の情報を付加することも可能である(付けなくても良い)。 戻り値 @retval, @return 戻り値を示すためのコマンドとしては二種類ある。 列挙型やブール値など、いくつかの項目に分類して説明したい時は@retval、ひとまとまりの文章で説明したい場合は@returnを使う。

説明したいことがたくさんある場合は、先に示した@parなどを使うのも良いだろう。 お好みで、先に示した@authorや@dateなどを使っても良いが、まず間違いなくメンテナンスされなくなると思うが…

☞目次へ戻る

[6-4] 関数の事前条件と事後条件

関数の中でassert()を使った場合、その表明内容を説明するのに適したdoxygenコマンドもある。 @pre、@postがそれで、以下に例を示す。

/** * @brief 簡易メモり割り当て * @param sz 割り当てサイズ * @return 割り当てたメモリ * @pre szは1〜MAXBUFの範囲内にあること。 * @post メモリ割り当ては常に成功する。 */ void *alloc(int sz) { void *p; assert(0 < sz && sz <= MAXBUF); /* 〜 */ assert(p != NULL); return p; }

出力例：

ちなみに、これらのコマンドはコードの中に直接書いても構わない。出力結果は、先の例と同じで、関数説明としてすべてまとめて表示してくれる。

void *alloc(int sz) { void *p; /** @pre szは1〜MAXBUFの範囲内にあること。**/ assert(0 < sz && sz <= MAXBUF); /* 〜 */ /** @post メモリ割り当ては常に成功する。**/ assert(p != NULL); return p; }

☞目次へ戻る

[6-5] 関数などの自動リンク

doxygenコメント内で、関数名などにリンクを付けることができる。 以下のように、関数名に続けて()を記述し、前後の文章とスペースで間を空けておく。

/** * @mainpage * リングバッファライブラリ * * @section main_api API一覧 * | API名 | 機能 | * |:-------------- |:-------------------------------- | * | Rbuf_ini() | リングバッファの初期化 | * | Rbuf_putChr() | リングバッファへ1文字出力 | * | Rbuf_getChr() | リングバッファからの1文字入力 | * | Rbuf_isEmpty() | リングバッファが空かどうかの判断 | * * @section main_usage 使用方法 * - あらかじめ Rbuf_ctl 型の変数を定義しておく。 * - その変数で Rbuf_ini() を呼び出す。 */

出力例：

関数ヘッダで@briefで記述したコメントがポイントした時に表示される。クリックすると該当の関数定義のページが表示される。 また、この例の「使用方法」欄のRbuf_ctlは構造体タグ名であるが、この前後にもスペースで間を空けているので、自動リンクが付いている。

このように、関数名以外にもいくつか自動リンクされるものがある。参考までに、以下に自動リンクの説明ページを貼っておく。

Automatic link generation

URL: http://www.stack.nl/~dimitri/doxygen/manual/autolink.html

当然のことながら、リンク先の関数にdoxygenコメントが付いてないと自動リンクされない。

なお、関数参照としては「参照」セクション内に書く流儀もあるだろう。そのような場合は@saコマンドが使用できる。

/** * @brief 一人じゃ何もできない関数 * @sa mama() と papa() */ void baby(void) { /* ... */ }

出力例：

☞目次へ戻る

[6-6] 注意、警告、バグ、todo

何らかの注意を喚起するために、doxygenコメントの中に以下の六種類の記述が可能である。 状況に応じて使い分ければ良いだろう。

/** * @brief 制御構造体 * * 非常に重要な構造体 * * @remarks 単なる情報を書きたいとき。 * @attention 注意を喚起したいとき。 * @warning 何らかの警告をしておきたいとき。 * @bug バグが存在するとき。 * (別ページで一覧がリスト化される。) * * @note 何らかのメモ書き。 * @todo やるべきことを書いておく。 * (これも別ページで一覧がリスト化される。) */ typedef struct Control { int member1; ///< 最初のメンバ int member2; ///< 次のメンバ int member3; ///< 三番目のメンバ } Control;

出力例：

@bugと@todoに関しては、@pageコマンドでも使われる「諸情報」ページ内に一覧がリスト化される(上の例でも「バグ」と「todo」には、該当ページへのリンクが付いている)。 「諸情報」ページのtodo一覧、バグ一覧は、それぞれリンクになっており、クリックするとそれぞれ該当のページが表示される。

各リンクをクリックした時に表示される画面。 それぞれ、doxygenコメントで書いたものが出力される。

出力例：

☞目次へ戻る

[7] インストール時に設定したもの

doxygen設定ファイルのDoxyfile内の設定で、必須なもの、調整が必要だったものなどを挙げておく。

Project

PROJECT_NAME

プロジェクトの名称。出力ドキュメントのページのタイトルとして使われる。デフォルトはMy Projectなので、好みの名称に変えておいた方が良いだろう。

OUTPUT_DIRECTORY

ファイルの出力先。適当な場所を設定しておく。

OUTPUT_LANGUAGE

日本語のドキュメントで出力して欲しいのでJapaneaseとしている。

TAB_SIZE

ソースコードのタブ幅を何文字としているかをdoxygenに教える。 デフォルトは4で、1～16の範囲で指定できる。自分はプログラムを4タブで使用しているのでデフォルトのままだ。

OPTIMIZE_OUTPUT_FOR_C

デフォルトは無効(NO)だが、有効(YES)にするとCプログラムに適した最適化をしてくれる。 原則的に自分はCでしか使わないので有効(YES)にしている。

MARKDOWN_SUPPORT

doxygen ver.1.8.0からはコメント内でのMarkdown記法がサポートされている。 この設定で、doxygenでMarkdown記法を使うかどうかを選択できる。 デフォルトで有効(YES)なので、Markdown記法がうっとうしい場合は無効(NO)にすれば良い。

Build

EXTRACT_STATIC

static定義された関数や変数をドキュメントに出力するかどうかを指定する。 デフォルトのままだと出力されない(NO)ため、自分はYESにしている。

EXTRACT_PRIVATE

Ｃ＋＋の場合privateメンバをドキュメントに出力するかどうかを本設定で選択する。 デフォルトのままだと出力されない(NO)ため、それが嫌ならばYESにすれば良い。 Ｃプログラマにとってはどうでも良いことだが。

GENERATE_TODOLIST

@todoコマンドのリストを別ページに作るかどうかを指定する。デフォルトで有効(YES)である。 特に必要ない場合は無効(NO)にする。

GENERATE_BUGLIST

@bugコマンドのリストを別ページに作るかどうかを指定する。デフォルトで有効(YES)である。 特に必要ない場合は無効(NO)にする。

Input

INPUT_ENCODING

入力プログラムの文字エンコーディング。 デフォルトがUTF-8であり、変える必要はないと思うが、恐ろしく古いプログラム(SHIFT_JISやEUC-JPファイル)などをそのまま読み込ませる場合には変える必要がある。

RECURSIVE

入力プログラムをサブディレクトリからも取り込む場合は有効(YES)とする。 デフォルトは無効(NO)なので、プログラムコードをサブディレクトリに分けている場合は有効(YES)にする必要あり。

USE_MDFILE_AS_MAINPAGE

この設定で総合概要(メインページ)を作るために任意のMarkdownファイルを指定できるようだ。 GitHubで用意したReadMe.mdを、そのまま使うこともできる。 関数名の自動リンクもやってくれるようだが、微妙にMarkdownの解釈が異なるようで、使うならば出力結果を確認してからの方が良い。

HTML

GENERATE_TREEVIEW

有効(YES)にすると、サイドパネルにツリー状の目次を付けてくれる。良かったら、どうぞ。

Dot

HAVE_DOT

図形描画でGraphvizのdotコマンドを使う場合は有効(YES)とする。

DOT_PATH

図形描画用のGraphvizのdotコマンドのあるパスを設定する。 ブランクにしておけば勝手にコマンドパスから探してくれるということだったのに、Mac OS Xでは見つけてくれなかった。なぜ？ しようがないので、dotのインストールされている/usr/local/binを設定してやる必要があった。

☞目次へ戻る

[vrlab]

Doxygen Install

Doxygen Install for Project

현재 프로젝트 문서화작업 진행중입니다.

이를 위해서 간략하게 인코딩 및 기타 설정과 관련하여 메모를 위해 포스팅을 하였습니다.

글내용을 바로 작성할까 하다가 어짜피 이미지는 Dropbox링크가 깨지면, 끝이니 Dropbox.html 링크를 걸어두도록 하겠습니다.

** 참고로 설치는 없고, 사용방법에 관해서 만 작성되어있음. - 제목은....Install인데..말이죠 - Dropbox posting Link

[vrlab]

Doxygen

Install

DoxyGen Install Link

Using Doxygen Reference

최근 Doxygen 버전의 UI와 유사한 slide 입니다. 전체적인 설명을 알기위해서 아래의 링크를 참조하시면 됩니다. link1

그리고 link2, link3, link4, link5 나머지 링크들을 참조하시면 금방 사용할 수 있습니다.

사용방법에 대해서는 시간날 때 posting! 을 다시 하도록(?) 해보도록 하겠습니다! 물론 바쁘고 귀찮으면 ..여기서 stop...

그리고 한글로 주석을 달 경우, 기본 설정대로 출력할 경우 되지 않으니, 아래 꼭 한글깨짐해결방법을 참조하시기 바랍니다. !

Reference

한글깨짐 문제 해결방법 Link

by vbflash

[baltazar-codes]

[goodanswerbiz]

Fixed Best Tips for documenting code using doxygen? #dev #it #asnwer

Fixed Best Tips for documenting code using doxygen? #dev #it #asnwer

Best Tips for documenting code using doxygen?

My team is starting to document our C code using doxygen, paying particular attention to our public API headers. There appears to be a lot of flexibility and different special commands in doxygen, which is great, but it’s not clear what’s a good thing and what’s a bad thing without trial and error.

What are your favourite ways to mark up your code,…

View On WordPress