C++向けドキュメンテーションツールの悩み覚書

理想のドキュメンテーションツールとは何か。備忘録です。
2
大山ゆっけ(蘇る鈴木佑輔) @trinity_site

doxygenのxml出力を読んで、autodoc的な機能を実行するものが欲しい

2011-05-28 13:38:39
大山ゆっけ(蘇る鈴木佑輔) @trinity_site

翻訳考えなければdoxygenでいいんだけど。

2011-05-28 13:39:14
大山ゆっけ(蘇る鈴木佑輔) @trinity_site

SphinxがC++erに流行ってる理由ってスタイルがイケててrstの文法がイケてるから?

2011-05-28 13:43:20
大山ゆっけ(蘇る鈴木佑輔) @trinity_site

いろいろなライブラリのドキュメンテーションを見てると、自動生成っぽい割には知ってるツールのリンク構成と違うものが結構ある。知らないツールがまだまだあるのかな。

2011-05-28 13:44:18
大山ゆっけ(蘇る鈴木佑輔) @trinity_site

C/C++の場合、最低限の引数の意味などはヘッダに載っていて欲しいものの、概念的な説明などまでヘッダに書くとコードが冗長になる。また、ドキュメントの改訂のためにヘッダに触るのもはばかられる。翻訳の管理まで考えるとドキュメントとヘッダは分離していた方が良い。

2011-05-28 13:47:57
大山ゆっけ(蘇る鈴木佑輔) @trinity_site

しかし、ドキュメントの漏れや、しらみつぶし的なドキュメント作成のためにはコード中の要素(クラスの定義など)からドキュメント化すべきものを抽出する機構が欲しい。

2011-05-28 13:49:13
大山ゆっけ(蘇る鈴木佑輔) @trinity_site

コードからドキュメント化対象を抽出するツールはコードの変更とドキュメントの変更の両方を追跡する必要がある。さらにドキュメント対象の単位は複数の翻訳言語でリンクしている必要がある。

2011-05-28 13:50:29
大山ゆっけ(蘇る鈴木佑輔) @trinity_site

翻訳しないという選択をした場合、コードの要素とドキュメントの要素のリンクのみを保てば良い。つまりautodoc。

2011-05-28 13:51:55
大山ゆっけ(蘇る鈴木佑輔) @trinity_site

javadocが生まれた理由は、javaにヘッダというものがなかったからじゃないかと思っている。

2011-05-28 13:53:03
大山ゆっけ(蘇る鈴木佑輔) @trinity_site

headerdocってバージョンアップしてるのかな。Linuxへのインストールに手こずった記憶と、別ディレクトリ同一ファイル名をうまく扱えなかった記憶が残ってる。

2011-05-28 13:57:23
大山ゆっけ(蘇る鈴木佑輔) @trinity_site

ツールを使っている場合、どのタイミングでどのリリースをどう翻訳するかという問題がある。関数などの構成要素の記述を人力で行い、コードとドキュメントを完全に分離した場合はこの問題はあまり大きくならなさそう。

2011-05-28 13:59:15
大山ゆっけ(蘇る鈴木佑輔) @trinity_site

reference の綴りが何回間違えても覚えられない。

2011-05-28 14:07:30
大山ゆっけ(蘇る鈴木佑輔) @trinity_site

本当のUbuntuerは興味を持った瞬間apt-getしている。

2011-05-28 14:08:27
大山ゆっけ(蘇る鈴木佑輔) @trinity_site

Ubuntuのリポジトリにはなんでもあるよ!(嘘

2011-05-28 14:08:48
大山ゆっけ(蘇る鈴木佑輔) @trinity_site

GTK-Docのマニュアル見てるけど、基本autotoolsにべったり結合してるのかな。単体のgtkdoc-*系コマンドの使い方がわからん。

2011-05-28 14:16:42
大山ゆっけ(蘇る鈴木佑輔) @trinity_site

C系で使うドキュメンテーションツールの有名どころってdoxygen、headerdoc、GTK-doc、sphinxあたり?前に他にも調べた記憶があるんだが・・・。

2011-05-28 14:27:42
大山ゆっけ(蘇る鈴木佑輔) @trinity_site

ドキュメント作成のリソースが限られてる場合は、リファレンス的なドキュメントにどれだけの価値があるのかという点も見逃せないなあ。概念的な説明と、ヘッダでの簡潔な仕様説明で十分ということも多そう。分野によるかな。

2011-05-28 14:30:43
大山ゆっけ(蘇る鈴木佑輔) @trinity_site

llvmでドキュメンテーションツール・・・って思ったけど、コメント捨てたら意味ないじゃん!

2011-05-28 14:43:06
大山ゆっけ(蘇る鈴木佑輔) @trinity_site

そもそも方針を理解してれば宣言を見ればわかるような要素にドキュメントを書く必要があるのか。

2011-05-28 14:46:05
大山ゆっけ(蘇る鈴木佑輔) @trinity_site

C++のライブラリのドキュメントをSphinxで作る方法の発表資料ってどっかにないかな。

2011-05-28 14:50:52