1日目はmyokoymさんの「Ruby/GTK3で作るカレンダーアプリ」でした。C言語で書かれていて、Autotoolsでビルドシステムを構築しているプロジェクトがあるとします。このプロジェクトのドキュメントツールとしてGTK-Docを使う方法を説明します。GTK-DocについてGTK-Docはその名の通りGTK+用のドキュメントツールです。GTK-Docは、公式サイトにも書いてある通り、一般的なドキュメントツールではなくGTK+に特化したドキュメントツールです。細かくいうと、GObjectに特化したドキュメントツールです。「GObjectに特化している」というのは、次の機能を備えているからです。GObjectのプロパティー専用のドキュメント機能GObjectのシグナル*1専用のドキュメント機能GObjectのクラスの継承関係を表示する機能これらは通常のドキュメントツールにはない機能です。GTK-DocはDocBookをバックエンドに使ったドキュメントツールなので他のドキュメントツールと同じくらい表現力があります。そのため、GObjectを使ったプロジェクトなら、他のドキュメントツールではなくGTK-Docを使ったほうがユーザーにとって使いやすいドキュメントを提供できます。GObjectを使っていないのであれば、別のドキュメントツールも検討したほうがよいでしょう。C++も使うなら確実に他のツールの方がよいです。GTK-DocはC++をサポートしていません。managerのリファレンスマニュアルはGTK-Docを使っています。これらのプロジェクトではGObjectを使っているからです*2。GTK-Docの使い方それでは、例を出しながらGTK-Docの使い方を説明します。ここで作るライブラリーはGitHubに置いてあります。Domain)にするので、自由に再利用してください。ここでは、「libsample」というライブラリーを作ります。このライブラリーの中にあるクラスはSampleGreeterだけです。GObjectを使ったプロジェクトを作成(GTK-Docはまだ使わない)作ったプロジェクトでGTK-Docを使うGObjectを使ったプロジェクトを作成それでは、GObjectを使ったプロジェクトを作成します。このセクションはそれほど大事なことではないので、興味のない人は飛ばしてもかまいません。このライブラリーの実装を用意します。.cも.hも「sample/」以下に置きます。クラス定義について、GObjectの使い方を知っている人は「いつもの感じ」と思うかもしれませんが、知らない人は面倒だと思うことでしょう。"Hello!";}コード中の次のようなコメントの中に書かれているドキュメントがGTK-Doc用のドキュメントです。ドキュメントを.cに書くドキュメントツールと.hに書くドキュメントツールがありますが、GTK-Docは主に.cです。言うと、実装のそばにドキュメントを書くスタイルということです。*/次に、これらのソースをビルドする部分を作ります。次のようなディレクトリー構成にします。greeter.hまず、configure.acを作ります。コメントを入れておいたのでなんとなくわかるでしょう。AC_CONFIG_FILESで指定したファイルなどを生成AC_OUTPUT続いてMakefile.amです。「aclocal」用の設定ぐらいのものです。m4/以下もパスに加える。渡せるようにしている。再帰的にsample/以下もmakeする。sample最後にsample/Makefile.amです。greeter.hautogen.shを用意すればビルドできます。--installそれではビルドしてみましょう。installこれで/tmp/local/lib/libsample.soができます。GTK-Docを使うこのプロジェクト用のドキュメントをGTK-Docで生成する仕組みを作ります。ポイントは次の4つです。autogen.shでgtkdocizeを使うconfigure.acでGTK-Docを検出するGTK-Doc用のファイルを作るファイルを作る前に、GTK-Docを使うようになった後のディレクトリー構造を示します。greeter.hdoc/以下を新しく作り、それに伴いトップディレクトリーにある次のファイルを変更します。Makefile.amautogen.shconfigure.acそれでは、autogen.shからいきましょう。GTK-Docを使うための補助的なファイルを生成するgtkdocizeというコマンドがあります。これは、autoreconfを実行するために必要なファイルも生成するので、autoreconfの前に実行します。gtkdocizeもautoreconfのようにm4/ディレクトリー以下にファイルをコピーするのでmkdirよりは後にします。--installconfigure.acでは、GTK-Docを検出するようにします。MakefileこれでGTK-Docを下準備はできました。それでは、GTK-Docの設定にいきます。GTK-Docの設定はdoc/reference/以下で行います。トップディレクトリーでmakeしてもdoc/reference/まで再帰的に降りていってくれるようにしましょう。次のファイルを編集します。渡せるようにしている。再帰的にsample/以下もmakeする。再帰的にsample/、doc/以下もmakeする。再帰的にreference/以下もmakeする。AC_CONFIG_FILESで指定したファイルなどを生成これでdoc/reference/までの道ができました。doc/reference/Makefile.amがGTK-Docの設定をする場所です。意外とパラメーターが多いなぁと思うことでしょう。そのまま従うのがよい。$(top_srcdir)/sample/Makefile.amで指定したものと同じものを指定すればよい。ビルドするディレクトリーが違うのでそこは考慮する必要がある。$(top_srcdir)/sample/Makefile.amで指定したものと同じものを指定すればよい。ビルドするディレクトリーが違うのでそこは考慮する必要がある。cleanでsample-sections.txtとsample.typesを削除する。$(DOC_MODULE).typesどのパラメーターも悩まずに設定できるはずです。新しく決めることはなく、事実を埋めていくだけです。次の2点を補足します。ドキュメントを生成するのにどうしてビルドオプションを指定するのかCLEANFILESに指定しているものはなにかまず、ビルドオプションについてです。GTK-Docはドキュメントを生成するために、ドキュメント対象のライブラリーを組み込んだ実行ファイルを作成します。その実行ファイルを実行してライブラリーのメタデータを動的に取得します。メタデータとはクラス階層やどんなプロパティーを持っているかなどです。GTK-DocがGObjectに特化したドキュメントツールなのでここまでやっているのです。次に、CLEANFILESに指定している次のファイルについてです。sample-sections.txtsample.typesGLibやGTK+での使い方をみると、どちらもリポジトリーに入れて管理することを期待しているファイルのようにみえます。ここではリポジトリーに入れずに自動で生成するようにします。理由は、どちらも手動で管理することが面倒だからです。sections.txtはドキュメント対象とする関数や構造体を列挙するファイルで、.typesは自分で作ったオブジェクト*3を列挙するファイルです。開発が進むにつれ、ここに列挙しなければいけないことが増えますが、それをいちいちやっていられません。これらのファイルはなければ前述したメタデータなどから自動的に作成されます。多少ゴミもまじりますが、手動で管理する手間を考えれば割にあいます。そのため、CLEANFILESに入れています。最後にドキュメントのエントリーポイントとなるXMLファイルとそこで使うファイルを作成して仕組みは完成です。ポイントは<xi:include>のところです。他は一度作ったら後はほとんど使いまわせます。</index></book>新しいクラスができたら対応する<xi:include>を増やしていきます。するとドキュメントに組み込まれます。version.xmlを参照しているので作ります。ここにはバージョン番号だけが入るので、.inからconfigureで作ります。sample/doc/reference/version.xml.in:1@VERSION@.inを作ったのでconfigure.acも変更します。AC_CONFIG_FILESで指定したファイルなどを生成これで仕組みができました。GTK-Docを使ったドキュメントを作ってみましょう。configureで--enable-gtk-docを指定することがポイントです。installこれで/tmp/local/share/gtk-doc/html/sample/index.htmlにHTMLができているはずです。まとめ実例を用いてプロジェクトのビルドシステムにGTK-Docを組み込む方法を説明しました。GTK+などGObjectベースのライブラリーを作っている場合はドキュメントはGTK-Docで提供することをオススメします。GObjectに特化した情報のドキュメントの作成が容易ですし、わりと小ぎれいなドキュメントができます。GTK-Docを使ってみてください。ここで作った例はGitHubに置いてあります。Domain)なので自由に再利用してください。kill(1)で送るシグナルとは違う。managerではGTK+を使っていません。GTK+がベースとしているライブラリーであるGLibやGObjectの機能だけを使っています。4.0とGFDLのデュアルライセンスで自由に利用できます。クリアコードはプログラミングが楽しいソフトウェア開発者を1名募集しています。クリアコードは「クリアコードをいい感じにする人」を1名募集しています。クリアコードはフリーソフトウェア開発で培った技術力を提供しています。Thunderbird)とRubyとGroonga(全文検索)に関連した開発を得意としています。