Doxygen

〜 ドキュメンテーションツール 〜

Doxygen

〜 Documentation tool 〜

概要 Abstract
Doxygen はソースコードを解析してドキュメント化するツール.C++, C, C#, Java, Python, PHP などに対応している.
Doxygen is a documentation tool which analyzes source codes. It can handle C++, C, C#, Java, Python, PHP etc.

オーバービュー Overview

Doxygen はプロジェクトの複数のファイルを一度に処理できる.使い方は簡単:

  1. C++などでソースコードを書く際に,Doxygenの書式でコメントを書いておく(オプション).
  2. ドキュメントのメインページなどを,Doxygenの書式で書く(オプション).
  3. プロジェクトの Doxygen 設定ファイルを書く(必須).
  4. Doxygen を実行してプロジェクトを解析(必須).

Doxygen 形式のコメントを書いていなくても,プログラムの構造を解析してくれるので,未知のプロジェクトのソースを読む際にも使える.

ドキュメント化した結果は,HTML, LaTeX 形式などで出力できる.

インストール

パッケージ doxygen をインストールするだけでよい.

ついでに graphviz をインストールしておくと,クラスの継承ツリーなどを可視化してくれるので,インストールしておこう.

Reference

使い方

詳細な使い方は,上記リファレンスが充実しているので,そちらを参照.

以下では,C++の場合について概説する.

Doxygen 形式のコメント

Doxygen では,C++のソースコードにブロック型のコメント

/*! DOXYGEN COMMENT */

または行コメント

//! DOXYGEN COMMENT

として説明,メッセージ,警告,などの情報を埋め込む.よって,コンパイラはコンパイル時にこれらの記述を無視する.

Doxygen コメントでは,Doxygen のコマンドを使って構造化する.Doxygen のコマンドは,バックスラッシュ (\) で始まる.

以下,典型的な記述例を紹介する.

ファイルヘッダ

ファイルの先頭に書く.

/*! \file    FILENAME
    \brief   BRIEF-COMMENT
    \author  AUTHOR
    \version VERSION
    \date    DATE
*/
  • FILENAME : ファイル名.
  • BRIEF-COMMENT : 簡単なコメント.
  • AUTHOR : 作者(省略可).
  • VERSION : バージョン(省略可).プロジェクトのバージョンと紛らわしくなるので,省略することも多い.
  • DATE : 日付(省略可).日付の後に簡単なコメントを書いてもよい.

例:

/*! \file    stl_math.h
    \brief   liblora - STL extension for mathmatical use  (header)
    \author  Akihiko Yamaguchi, akihiko-y@example.com
    \date    Jun.13, 2010-
    \date    Aug.25, 2010   Added GetMaxNorm
    \date    Nov.02, 2010   Modified ConstrainVector

    Copyright (C) 2010  Akihiko Yamaguchi

    This file is part of SkyAI.

    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    ....
*/

クラス

クラスの定義の前に書く.

/*!\brief Hoge hoge. this class is hoge hoge. */
class THogeHoge
{
...
};
  • \brief の後に説明を書く.面倒なときは \brief を省略して説明だけ書いてもよい.
  • その後に \note コマンドを使って,ノートを書いてもよい(オプション).
  • \warning コマンドを使って,警告を書いてもよい(オプション).

変数

変数(メンバ変数も含む)のコメントは,以下のように変数の前に書く記法がある:

//! Sample variable.
type Sample;

変数の後に書く場合は,小なり記号 (<) を付ける必要がある:

type Sample; //!< Sample variable.

関数

関数(メンバ関数も含む)のコメント:

/*!\brief hogehoge
    \param[in]  param1  hoehoe
    \param[out] param2  hoehoe
    \return hoehoe  */
type3 Func(type1 param1, type2 &param2);
  • \brief : 概要を後に書く.\brief を書かずに概要を書いてもよい.
  • \param[in] : 入力用の引数(省略可).
  • \param[out] : 出力用の引数(省略可).
  • \param : 引数(省略可).
  • \return : 戻り値に関する説明(省略可).

メインページなど

README ファイルなどを Doxygen スタイルで書いておくことで,ドキュメントのメインページなどを作成できる.Doxygen スタイルのコメントのみを収録したファイルには .dox という拡張子を付けるとよい.

メインページの例 (README.dox):

/*! \mainpage
SkyAI -- Highly modularized Reinforcement Learning library
for real and simulation robots to learn behaviors.

Copyright (C) 2009, 2010, 2011, 2012  Akihiko Yamaguchi

\section Overview
--------

SkyAI is a highly modularized Reinforcement Learning library for real
and simulation robots to learn behaviors.

...

\section Installation and Usage
--------

Please visit http://skyai.org/

--
Akihiko Yamaguchi

Last updated: Thu May 31 11:21:20 JST 2012
*/
  • \mainpage : メインページであることを表す.
  • \section : 章見出し.次の行に水平線 -------- を入れておく必要がある.

Doxygen コメントのスタイルガイド

  • Doxygen コメントの記法には,ブロック型: /*! DOXYGEN COMMENT */ ライン型: //! の組み合わせと,ブロック型: /** DOXYGEN COMMENT */ ライン型: /// の組み合わせがある.プロジェクトやチームの過去のスタイルを参照し,それに合わせること
  • Doxygen のコメントには,バックスラッシュ (\) で始める書き方と,アットマーク (@) で始める書き方がある.同様に,プロジェクトやチームの過去のスタイルを参照し,それに合わせること

設定ファイル

まず,doxygen を使ってデフォルトの設定ファイルを生成し,それを各プロジェクトに合わせて変更する.各設定項目は「タグ」と呼ばれる.

デフォルトの設定ファイルを生成する:

doxygen -g dxconfig
  • dxconfig : 生成される設定ファイルのファイル名.例えば dxconfig.

既にある設定ファイルのバージョンを更新する:

doxygen -u dxconfig

よく使うタグの設定例

# Encoding used for all characters in the config file
DOXYFILE_ENCODING      = UTF-8
# Project Name
PROJECT_NAME           = libskyai
# Output directory that stores the generated documentation(s)
OUTPUT_DIRECTORY       = build/doc
# Language of the user interface. Alternatives: Japanese, Japanese-en (Japanese with English messages)
OUTPUT_LANGUAGE        = English
# Used to strip a user-defined part of the path
STRIP_FROM_PATH        = $(HOME)/proj/skyai
# Input directories/files
INPUT                  = ../include ../src \
# Character encoding of the source files
INPUT_ENCODING         = EUC-JP
# File patterns
FILE_PATTERNS          = *.h \
                         *.hpp \
                         *.c \
                         *.cc \
                         *.cpp \
                         *.cxx \
                         *.c++ \
                         *.dox
# YES: subdirectories should be searched
RECURSIVE              = YES
# Generate a html documentation
GENERATE_HTML          = YES
# Name of the directory into which the HTML documentation is output
HTML_OUTPUT            = html
# LaTeX setup
GENERATE_LATEX         = NO
LATEX_OUTPUT           = latex
# YES: evaluate all C-preprocessor directives
ENABLE_PREPROCESSING   = YES
# YES: Doxygen will expand all macro names in the source code
MACRO_EXPANSION        = YES
# Predefined macro name(s)
PREDEFINED             = __cplusplus
# NO: does not allow to remove the function-like macros
SKIP_FUNCTION_MACROS   = NO
# use Graphviz
HAVE_DOT               = YES
# YES: the inheritance and collaboration graphs will show the relations between templates and their instances
TEMPLATE_RELATIONS     = YES
# YES: a search engine should be used
SEARCHENGINE           = YES

追加:

# If the SOURCE_BROWSER tag is set to YES then a list of source files will
# be generated. Documented entities will be cross-referenced with these sources.
# Note: To get rid of all source code in the generated output, make sure also
# VERBATIM_HEADERS is set to NO.
SOURCE_BROWSER         = YES
# Setting the INLINE_SOURCES tag to YES will include the body
# of functions and classes directly in the documentation.
INLINE_SOURCES         = YES
# Setting the STRIP_CODE_COMMENTS tag to YES (the default) will instruct
# doxygen to hide any special comment blocks from generated source code
# fragments. Normal C and C++ comments will always remain visible.
STRIP_CODE_COMMENTS    = NO
# If the REFERENCED_BY_RELATION tag is set to YES
# then for each documented function all documented
# functions referencing it will be listed.
REFERENCED_BY_RELATION = YES
# If the REFERENCES_RELATION tag is set to YES
# then for each documented function all documented entities
# called/used by that function will be listed.
REFERENCES_RELATION    = YES

実行

設定ファイルを指定して Doxygen を実行:

doxygen dxconfig
  • dxconfig : 設定ファイル.

トップ   編集 凍結 差分 バックアップ 添付 複製 名前変更 リロード   新規 一覧 単語検索 最終更新   ヘルプ   最終更新のRSS
Last-modified: 2013-10-08 (火) 21:39:13 (1745d)