lisz-works

技術と興味の集合体

コンソールで「ソース→ドキュメント生成!」Doxygen使い方

【スポンサーリンク】

Doxygen

ソースファイルからドキュメントを生成するツール「Doxygen」についてです!

コレを使えば、ソースを修正→Doxygenで出力とするだけで、ソースとドキュメントが一致しちゃう!

doxygenのインストール

www.stack.nl

「A binary distribution for Windows. All versions of Windows since XP are supported.」

ftpかhttpのどちらのリンクでもOK。

太字を見てみると64bit版もあるようなので、64bitの方はこちらでOKかと!

インストールは、はいはい言ってればOKです。

インストール確認

インストーラなので、特にやらなくてもOKかとは思いますが……

「念のため確認したい!」という方は、下記コマンドでバージョン情報が出ればOKかと!

>doxygen -v
1.8.14

Doxygenコメント

Doxygenは、指定された記述方法でコメントを書いておくことで、ドキュメントを自動生成してくれます。

Doxygen用のコメントの書き方はこちらを参照しました。

qiita.com

テスト用ソース

こんな感じで3つのソースファイルを作成しました。

Main.c

#include <stdio.h>
#include "calc.h"

/**
* @fn int main(void)
* @brief メイン関数
* @return int 終了コード
*/
int main(void)
{
    printf("hello\n");
    add(1, 2);
    sub(5, 3);
    show(10, 5);
    
    return 0;
}

calc.c

#include <stdio.h>
#include "calc.h"

/**
* @fn int add(int x, int y)
* @brief 加算関数
* @param[in] x(数値1) 数値1
* @param[in] y(数値2) 数値2
* @return int 加算結果
*/
int add(int x, int y)
{
    return x + y;
}

/**
* @fn int sub(int x, int y)
* @brief 減算関数
* @param[in] x(数値1) 数値1
* @param[in] y(数値2) 数値2
* @return int 減算結果
*/
int sub(int x, int y)
{
    return x - y;
}

/**
* @fn void show(int x, int y)
* @brief 一括計算結果表示関数
* @param[in] x(数値1) 数値1
* @param[in] y(数値2) 数値2
*/
void show(int x, int y)
{
    printf("x,y ---\n");
    printf(" add > %d\n", x, y);
    printf(" sub > %d\n", x, y);
}

calc.h

#ifndef __CALC_H__
#define __CALC_H__

int add(int x, int y);
int sub(int x, int y);
void show(int x, int y);

#endif

Doxyfileの作成

まずはDoxygenの設定ファイル「Doxyfile」を作成します。

GUIで作る方法もありますが、今回はCUIについて説明していきます。

設定ファイルのテンプレートを出力

出力したいフォルダをコマンドプロンプトで開いて

doxygen -g

を叩く。

なんだったらエクスプローラで出力したいフォルダを開いて、アドレスバーにこのコマンドを打ってもOK!

変更する箇所

このあたりを変更すればOKでした!

項目名 備考
PROJECT_NAME 任意のプロジェクト名
OUTPUT_LANGUAGE English/Japanese 出力言語をお好みで
EXTRACT_ALL YES
INPUT ソース置き場のパス
INPUT_ENCODING ソースのエンコード Shift-JISは「CP932」
FILE_PATTERNS ソースの拡張子 例:C系なら「*.c *.cpp *.h」など
RECURSIVE YES
EXCLUDE_PATTERNS 除外パス 例: .\lib\配下なら「*/lib/*」
GENERATE_LATEX YES/NO LATEXの出力有無お好みで

ドキュメントの生成

Doxyfileのあるフォルダを、コマンドプロンプトで開いて

doxygen

を実行!

あとは勝手に処理されるので、

finished...

が表示されるまで待ちましょう!

ドキュメントを見る

ドキュメントの生成が完了すると

.\html

が作られます。

この中にある「index.html」がドキュメントのトップページになります。

コレを開いて、メニューを選んでいけば、ドキュメントの詳細が見ることができます!

こんな感じ!

出力サンプル

あとがき

Doxygenがあれば、ソースの修正の影響で「ソースとドキュメントの内容が全然違う……」なんていう絶望的状況も回避できちゃうんじゃないでしょうか!?

ぜひとも使ってみてください!

ドキュメントに自動で図も入れたい!という方はコチラも合わせてどうぞ!

www.lisz-works.com