08 Oct 2012, 23:34

DoxygenとJenkinsを連携させてみた。

前回までの記事で、Doxygenの基本的な使い方を書いた。

Doxygenでドキュメント管理しても、実は見ないことのほうが多かったりする。その理由は、

  • 目につく場所にないから
  • ソースコードを修正するたびにdoxygenファイルを作り直すのが面倒だから
  • ソースの修正がドキュメントに反映されていないから

などなど、考えられるが、Jenkinsを利用して、Jenkinsジョブを流すたびにドキュメントを更新し、さらにはJenkinsから閲覧できるようにすれば、上に上げた課題は解決するかも。

というわけで、JenkinsとDoxygenを連携してみる。

Doxygen Pluginのインストール

JenkinsにはDoxygen Pluginというものがあるので、インストールする。

[Jenkinsの管理] > [プラグインの管理] からDoxygen Plugeinを選択して、ダウンロードとインストール。

インストールできたらジョブの[設定] からビルドのDoxygenの生成コマンドを追加。

ex.) doxygen doxygen.conf

[ビルド後の処理の追加]から[Publish Doxygen]を選択。

doxygenの設定ファイルを指定する。

image

ビルドを実行して、Doxygenファイルを生成してみる。

DoxyGen HTMLというメニューが現れて、リンク先からDoxygenを閲覧することができる。


注意: こんなエラーがでたら、Doxygenのフォルダパスを指定している。

フォルダではなくて、Doxyfileを指定する。

Publishing Doxygen HTML results.
FATAL: error
java.io.FileNotFoundException: C:\Users\TSUNEMICHI\Dropbox\src\mock_study\html (アクセスが拒否されました。)
    at java.io.FileInputStream.open(Native Method)
    at java.io.FileInputStream.<init>(Unknown Source)
    at hudson.plugins.doxygen.DoxygenDirectoryParser.loadDoxyFile(DoxygenDirectoryParser.java:208)
    at hudson.plugins.doxygen.DoxygenDirectoryParser.retrieveDoxygenDirectoryFromDoxyfile(DoxygenDirectoryParser.java:345)
    at hudson.plugins.doxygen.DoxygenDirectoryParser.invoke(DoxygenDirectoryParser.java:53)
    at hudson.plugins.doxygen.DoxygenDirectoryParser.invoke(DoxygenDirectoryParser.java:14)
    at hudson.FilePath.act(FilePath.java:842)
    at hudson.FilePath.act(FilePath.java:824)
    at hudson.plugins.doxygen.DoxygenArchiver._perform(DoxygenArchiver.java:219)
    at hudson.plugins.doxygen.DoxygenArchiver.perform(DoxygenArchiver.java:176)
    at hudson.tasks.BuildStepMonitor$2.perform(BuildStepMonitor.java:27)
    at hudson.model.AbstractBuild$AbstractBuildExecution.perform(AbstractBuild.java:717)
    at hudson.model.AbstractBuild$AbstractBuildExecution.performAllBuildSteps(AbstractBuild.java:692)
    at hudson.model.Build$BuildExecution.post2(Build.java:183)
    at hudson.model.AbstractBuild$AbstractBuildExecution.post(AbstractBuild.java:639)
    at hudson.model.Run.execute(Run.java:1527)
    at hudson.model.FreeStyleBuild.run(FreeStyleBuild.java:46)
    at hudson.model.ResourceController.execute(ResourceController.java:88)
    at hudson.model.Executor.run(Executor.java:236)
Build step 'Publish Doxygen' changed build result to FAILURE






                    

08 Oct 2012, 22:38

Doxygen C言語のコメント備忘録

前回の記事では、Doxygenの導入をまとめたので、

ここではC言語/C++で使えるコメント(Doxygenタグ)の記入方法をまとめる。

公式サイトには、全てのコメント使用例が書いてあるが、ちょっと多すぎる。

http://www.doxygen.jp/commands.html#cmdparam

Doxygenの基本コメントまとめ

doxygenコメントは冒頭に /*! をつける。

C言語ソースでよく利用する(?)コメント(タグ)を列挙する。

共通でよく使う

@brief 説明文

 

  • インデントをそろえたハイフン’-“で箇条書きが表見できる。
  • /*@{*/ と/*@}*/ で囲むことで、グループ化できる。

ファイルヘッダ関係

@file ファイル名
@date 日付
@author 作者
@version 版数/バージョン
@par ユーザ定義の記述

 

[text]

/*!

  • @file sample.c

*

  • @dateツꀀツꀀツꀀ Created on: 2012/09/05

  • @authorツꀀ Author: きつね

  • @version 1.0

  • @briefツꀀSツꀀ GoogleMock実験用

  • @parツꀀツꀀツꀀツꀀ History 新規作成

*/

[/text]

image

宣言関係

これらの宣言は、ファイルのどこかに @fileと記載されている必要がある。

@struct 構造体
@enum 列挙型
@def 定義
@var グローバル変数

 

[text]

/*! @struct NUM

*ツꀀ @briefツꀀ ナンバー

*/

typedef struct NUM

{

int num;ツꀀツꀀツꀀツꀀ /*!< 数ツꀀツꀀツꀀツꀀツꀀツꀀ */

int count;ツꀀツꀀ /*!< カウント */

}NUM;

/*! @struct RET

*ツꀀ @bruefツꀀ 戻り構造体

*/

typedef struct RET

{

int ret;ツꀀツꀀツꀀツꀀ /*!< 戻り値ツꀀツꀀ */

int count;ツꀀツꀀ /*!< カウント */

}RET;

/*!@def

  • @brief 数の上限

*/

#define NUM_MAXツꀀ 10

/*!@enumツꀀ collor

  • @brief 色

*/

typedef enum{

red,ツꀀツꀀツꀀツꀀ /*!<赤 */

blue,ツꀀツꀀツꀀ /*!<青 */

yellowツꀀツꀀ /*!<黄色 */

}collor;

[/text]

  • メンバの説明は、/*!< hogehoge */ でも書ける。

image

関数ヘッダ関係

 

@fn 関数宣言
@breaf 要約説明
@param param <引数名> { 引数説明 } 関数の引数
param[in] 入力フォーマット
param[out] 出力フォーマット
param[in,out] 入出力フォーマット
@return { 戻り値の記述 } 戻り値の記述
@detail 詳細説明

 

[text]

/*!

  • @fnツꀀツꀀツꀀツꀀツꀀツꀀツꀀ get_ret

  • @brief

  • @param[in] void

  • @returnツꀀツꀀツꀀ 結果の数

  • @detailツꀀツꀀツꀀ 数をライブラリから取得し、その結果によって処理を分岐する

*/

[/text]

image

03 Oct 2012, 22:38

Doxygenの使い方(セットアップ編)の備忘録

最近、モノ忘れが激しくて困る。

そんな、おとぼけおじさんの、ドキュメント生成ツールDoxygenの使い方の備忘録。

今回は導入まで。

Doxygenのダウンロードとインストール

公式サイトからDoxygenをダウンロード&インストール。

または、自分はCygwinを使っているので、setup.exeからダウンロード&インストール。

image

Doxygenの設定ファイルの作り方

Doxygenを試したいプロジェクトディレクトリで、以下のコマンドを実行。

doxygen 窶堵ツꀀ doxygen.conf

doxygen.confは設定ファイル名なので、任意の名前でよい。実行すると、設定ファイルが出来上がる。設定する項目はたくさん用意されているけれども、とりあえず以下の項目を編集した。

PROJECT_NAME プロジェクト名 mock_study
OUTPUT_LANGUAGE 言語 Japanese
INPUT 入力ディレクトリのパス src/
INPUT_ENCODING 入力ソースのエンコード SHIFT_JIS/EUC-JP
ここをいじらないと、
Doxygenが文字化けする。
FILE_PATTERNS 拡張子指定 *.c *.h
GENERATE_LATEX LATEX形式出力 NO

 

  • デフォルトのエンコードはUTF-8なので、
  • デフォルトではHTMLとLATEX形式の出力が有効になっている。

Doxygenでドキュメントを生成してみる

設定ファイルを引数として、コマンドを実行する。

doxygen doxygen.conf

html/というフォルダができ、その下にドキュメントが生成される。

閲覧するには、index.htmlを開く。

C言語でDoxygenを利用するときの注意点

出来上がったindex.htmlを開くと、

わお、ソースファイルがない!ヘッダファイルしかない!

いろいろ悩んだ結果、設定ファイルで、

EXTRACT_ALLツꀀツꀀツꀀツꀀツꀀツꀀツꀀツꀀツꀀツꀀツꀀ = YES

とすると、Cソースもドキュメント化された。

18 Apr 2012, 11:16

Cygwinでdoxygenコンパイルエラ-

doxygenのソ-スをCygwinでコンパイルしたら以下のエラ-が出てコンパイルが停止

./configure --prefix /usr/local
Autodetected platform win32-g++...
Checking for GNU make tool... using /usr/bin/make
Checking for GNU install tool... using /usr/bin/install
Checking for dot (part of GraphViz)... not found!
Checking for perl... using /usr/bin/perl
Checking for flex... not found!

いろいろと足りないものがあるので指摘されたものをsetup.exeで手に入れて再度実行。

./configreは通る。

しかしmakeでエラ-

portable_c.c:1:19: iconv.h: No such file or directory

調べて見たらlibiconvというものが必要みたい。

Cygwin の setup.exeで手に入れて再度makeを実行したら、コンパイル成功ツꀀhttp://sourceforge.net/projects/doxygen/forums/forum/130996/topic/3136999

make install で再度エラ-

$ make install
/usr/bin/install -d //usr/local/bin
/usr/bin/install: cannot create directory `//usr': Read-only file system
Makefile:76: recipe for target `install' failed
make: *** [install] Error 1

どうも ‘//usr’が悪いみたいなので

./configure --prefix usr/local

と変更したら成功。

続いてツꀀmake docs_installで失敗

epstopdfがないと言われる。

ここでわからず挫折。