質問: 趣味で C/C++でやっています。 ( 今回はあまり言語は関係ないですが。一応。 ) 皆さんは自分用のライブラリを組んだ場合、 Documentation というのでしょうか? boost とかについている、 「こういうクラスがあり、こういうメンバ関数 ( メソッド ) がある。 戻り値はこれこれを返す可能性があり、もし失敗すればこういう例外を投げる可能性がある」 みたいなやつありますよね? そういったのはどうしていますか? たとえば「 HTMLファイルに記録している。」とか、 「Documentation? そんなもの作るより普通にヘッダファイルなりcppファイルなり直接読むね。」とかです。 私は自分が使いやすいように クラス化 ( あるいは関数化 ) して自分用のライブラリを作成しています。 たとえば、C言語 の FILEポインタを使ってファイルの入出力をする場合を考えてみます。 fopenでファイルを開く -> ファイルのデータを読み込む -> fcloseでファイルを閉じる のような操作が煩わしいのでクラス化するみたいな感じだとします。 CIoFileクラスなるものを作って コンストラクタでファイルを開いて デストラクタでファイルを閉じる...みたいな。 定義とかのようなプログラム自体は今回の場合は問題でないのでスルーします。 私が聞きたいのは、 この CIoFileクラスのコンストラクタで引き受ける引数、投げられる例外, メンバ関数はどういうのがあり... というのをどこに記述するかです。 ソースコードにではなくて、「あー、CIoFileっていうクラスあったけど、引数どんなだったかな? 例外投げたっけ?」とかみたいに ド忘れしたりしますよね。 その対策というか、Documentation があったらそれでチェックできると思うので。 ただ、HTMLでやると いちいちクラスごと ( あるいは関数ごと ) に 立てる必要があるのでどうなのかな... と。 Word を使って HTML っていう方法もありますが、一ページごとに "ディレクトリ" ができますし... 皆さんはどういう風にやっているのでしょうか? ベストアンサーは、試してみたいと思う方にする予定です。 宜しくお願い致します。
回答: 私はヘッダーにDoxygen形式でコメントを書いています。 Doxygenというツールを使うとソースのコメントからHTMLなど(形式はいくつか選択可能)のドキュメントを作成できます。ソースファイル内にドキュメントを書くのでメンテナンスが集約でき、ソースとドキュメントの乖離をなくすことができます。リファレンスマニュアルの作成にとても便利です。