今回はdoxygenというドキュメント自動作成ツールを使用してみたいと思います．
このツールを使用すると例えば次のようなページを作成することができます．ライブラリの関数を調べる際にこういうページを目にすることがある方もいると思います．

自作ライブラリの説明を見やすく，辞書的に使用することができるようになるのでとても便利です．

インストール

下記コマンドでインストールします．

$ sudo apt-get install graphviz
$ sudo apt-get install doxygen

doxygenではインクルードファイルなどの依存関係をグラフで描画してくれます．
graphvizはグラフ描画のために必要になりますので，合わせてインストールします．

設定ファイルの作成

例えば次のようなファイル構成のライブラリがあったとします．

sample
 + CMakeLists.txt
 + src
 |  + sample.cpp
 |  +   ...
 + include
 |  + sample.h
 |  +   ...
 + doc   <追加

まずはじめにdoxygenでドキュメントを作成するためのディレクトリを追加しましょう．今回ははdocというディレクトリで進めていきます．
docディレクトリに移動して，doxygenの設定ファイルを作成します．

$ mkdir doc
$ cd doc
$ doxygen -g

doxygen -gコマンドでdoxygenの設定ファイルDoxyfileが作成されます．

Doxyfileの編集

いくつか設定を変更する必要があります．

$ sudo vim Doxyfile

とりあえず私の気になったものと最低限の設定を取り上げていきます．

035行   PROJECT_NAME = "sample"
095行   OUTPUT_LANGUAGE = Japanese
774行   INPUT = ../
805行   RECURSIVE = YES

PROJECT_NAME
プロジェクト名．変更しましょう．

OUTPUT_LANGUAGE
HTMLなどで出力する際の表示言語設定．

INPUT
doxygenに読み込ませるディレクトリを指定．今回はsampleディレクトリ全体を指定します．

RECURSIVE
サブディレクトリを管理対象に含めるかどうか．基本的にはYESになると思います．

ドキュメントの作成

Doxyfileのあるディレクトリで下記コマンドでドキュメントを作成します．

$ doxygen

作成が終わるとhtmlディレクトリが作成されます．その中にindex.htmlというものがあると思うので，お好きなブラウザで開いてみましょう．
ドキュメント化したいソースファイルを全くいじっていないので，not documentedといったwarningが出るかと思いますが，今回はドキュメントhtmlページがきちんと作成できることを確認したかったので気にせず行きましょう．

コメントの作成

あとはdoxygenの書式にしたがってコメントを加えていきましょう．