Introduction

Doxygenは各種言語向けのドキュメンテーションシステムである。 対応言語:

  • C++
  • C
  • Java
  • Object-C
  • Python
  • IDL
  • PHP (一部)
  • C# (一部)
  • D (一部)

Doxygenには次の利点がある:

  1. 文章化されたソースファイルセットから、HTML形式やlatex形式でのリファレンスマニュアルを生成することができる。 ドキュメントはソースファイルから直接抽出される。
  2. 文章化されていないソースファイルから、コードの構造を抽出するように設定がすることが可能である。 これにより大規模で分散化されたソースの中を探ることが容易になる。 様々な要素間の関係が、内包・依存図。継承図、及びコラボレーション図によって視覚化される。 これらは全て自動で行なわれる。

機能

  • ドキュメントの執筆者に対して、非常に少ない労力しか要求しません。 プレーンテキストを書くのですが、より装飾され、構造化された HTML を出力するのに、 いくつかの doxygen の特殊コマンドを使うことができます。
  • C/C++、Java、(Corba およびマイクロソフトの) Java、Python、 IDL、C#、Objective-C をサポートしており、D と PHP のソースにもある程度対応しています。
  • ファイル、名前空間、パッケージ、クラス、構造体、共用体、テンプレート、 変数、関数、typedef、列挙、およびマクロ定義のドキュメンテーションに対応しています。
  • Java Doc (1.1)、Qt-Doc、および ECMA-334 (C# 仕様) と互換。
  • クラス図とコラボレーション図をHTML形式 (クリック可能なイメージマップ) と (Encapsulated Post Script イメージ)で自動生成します。
  • Graphviz ツールキットの dot ツールを使って、包含依存図、コラボレーション図、グラフィカルなクラス階層図を生成します。
  • コメントの挿入箇所が可変です。ヘッダファイル(要素の宣言の前)、ソースファイル(要素の定義の前)、別ファイルなどに文を挿入できます。
  • クラスのメンバーすべて(継承メンバーも含む)のリストを、保護レベルを付けて生成します。
  • 文をオンライン形式(HTML,UNIX man ページ)、オフライン形式(, RTF) 両方同時に出力します(出力不可にすることもできます)。どの形式も、読みやすく最適化できます。
  • 更に、Microsoft HTML Help Workshop (Windowsのみ)を使ってHTML出力から圧縮HTMLを生成したり、 出力からPDFを生成したりもできます。
  • フルなCプリプロセッサを含んでいるため、条件付コード断片の解析や、マクロ定義の全部または部分を拡張することができます。
  • public,protected,privateセクションを自動判別し、Qt固有のsignal,slotsセクションも自動判別します。privateメンバーの抽出もオプションでできます。
  • ドキュメント付けされたクラス、ファイル、名前空間、メンバーへの参照を自動生成します。 グローバル関数、グローバル変数、型定義、定義、列挙のドキュメンテーションもサポートします。
  • 基底・スーパークラスや、継承・多重定義メンバーへの参照を自動生成します。
  • クラスやメンバーのドキュメントから文字列や単語を高速で検索する、ランクベースのエンジンがあります。
  • ご自分のドキュメントに通常のHTMLタグを挿入できます。doxygenはそれらを、 , RTF, manページなどの等価なものに置き換えます。
  • 他のプロジェクト(またはプロジェクトの中のほかの部分)のために生成されたドキュメンテーションへの参照を、場所に依存しない方法で許します。
  • ドキュメンテーションで自動的にクロス参照されるソースコードの例を含めることができます。
  • ドキュメント付けされていないクラスを含めることができます。これにより、実装の詳細を見なくても(大量の)コードの構造とインタフェースを早く知ることができます。
  • ソースコードの中で、(ドキュメント付けされた)要素のクロスリファレンスを自動で作れます。
  • ソースコードの断片は、読みやすいようにその同意語が強調されます。
  • ドキュメント中に、関数・メンバー・クラスの定義を含められます。
  • すべてのオプションは、編集しやすく注釈も付けられる、設定ファイルに保存されています。
  • ドキュメンテーションと検索エンジンは、場所やマシン間で移動できます。その際ドキュメンテーションの再生成をする必要がありません。
  • 大きなプロジェクトでも容易に対応できます。

doxygen は、C/C++言語ならどんなプロジェクトにも対応しますが、当初はTroll TechのQt ツールキットを利用するプロジェクトに使えるよう特に設計されました。 私は、doxygen をQtコンパチブルにする努力をしてきました。 ですので、doxygenはQtソースコードに含まれるドキュメンテーションを読めますし、Troll Techが生成するクラスブラウザによく似たものを作れます。 doxygenは、Qtが使うシグナルやスロットのような拡張コードを理解します。

doxygenを使ったりQtの非公開クラスブラウザジェネレータを使って生成された既存のドキュメンテーションへのリンクを、自動で生成することもできます。 Qtベースのプロジェクトでは、Qtツールキットに属するメンバーやクラスを参照すると、必ずQtドキュメンテーションへのリンクが生成されるということです。 これは、ドキュメンテーションの位置には関係なく生成されます。

reference

Install

Debian etch

パッケージ「doxygen」「doxygen-gui」をapt-get install。 終わり。

Others

Manual/Install

基本的な使用方法

設定ファイル

始めに設定ファイルのテンプレートを作成:

doxygen -g <config-file>

<config-file>を省略すると、Doxyfileという名のファイルが作成される。 同名のファイルが既にあった場合、doxygenは設定テンプレートを生成する前に、 <config-file>.bakという名前に変更する。

各種設定については設定テンプレート、マニュアルを参照。

設定箇所

http://www.doxygen.jp/starting.html

  • PROJECT_NAME
  • OUTPUT_DIRECTORY
    • doc/
  • EXTRACT_ALL
    • YES
  • EXTRACT_PRIVATE
    • YES
  • EXTRACT_STATIC
    • YES
  • EXTRACT_LOCAL_CLASSES
    • YES
  • SOURCE_BROWSER
    • YES
  • INLINE_SOURCE
    • YES

実行

設定ファイルを元に、ドキュメントを作成する:

doxygen <config-file>

<config-file>を省略した場合、デフォルトでDoxyfileが呼ばれる。