- trinity_site
- 5908
- 1
- 2
- 0
いろいろなライブラリのドキュメンテーションを見てると、自動生成っぽい割には知ってるツールのリンク構成と違うものが結構ある。知らないツールがまだまだあるのかな。
2011-05-28 13:44:18C/C++の場合、最低限の引数の意味などはヘッダに載っていて欲しいものの、概念的な説明などまでヘッダに書くとコードが冗長になる。また、ドキュメントの改訂のためにヘッダに触るのもはばかられる。翻訳の管理まで考えるとドキュメントとヘッダは分離していた方が良い。
2011-05-28 13:47:57しかし、ドキュメントの漏れや、しらみつぶし的なドキュメント作成のためにはコード中の要素(クラスの定義など)からドキュメント化すべきものを抽出する機構が欲しい。
2011-05-28 13:49:13コードからドキュメント化対象を抽出するツールはコードの変更とドキュメントの変更の両方を追跡する必要がある。さらにドキュメント対象の単位は複数の翻訳言語でリンクしている必要がある。
2011-05-28 13:50:29翻訳しないという選択をした場合、コードの要素とドキュメントの要素のリンクのみを保てば良い。つまりautodoc。
2011-05-28 13:51:55headerdocってバージョンアップしてるのかな。Linuxへのインストールに手こずった記憶と、別ディレクトリ同一ファイル名をうまく扱えなかった記憶が残ってる。
2011-05-28 13:57:23ツールを使っている場合、どのタイミングでどのリリースをどう翻訳するかという問題がある。関数などの構成要素の記述を人力で行い、コードとドキュメントを完全に分離した場合はこの問題はあまり大きくならなさそう。
2011-05-28 13:59:15GTK-Docのマニュアル見てるけど、基本autotoolsにべったり結合してるのかな。単体のgtkdoc-*系コマンドの使い方がわからん。
2011-05-28 14:16:42C系で使うドキュメンテーションツールの有名どころってdoxygen、headerdoc、GTK-doc、sphinxあたり?前に他にも調べた記憶があるんだが・・・。
2011-05-28 14:27:42ドキュメント作成のリソースが限られてる場合は、リファレンス的なドキュメントにどれだけの価値があるのかという点も見逃せないなあ。概念的な説明と、ヘッダでの簡潔な仕様説明で十分ということも多そう。分野によるかな。
2011-05-28 14:30:43さっきのリンク、なんか怪しい。 こっちをよく読む。 http://sphinx-users.jp/doc10/examples.html
2011-05-28 15:08:08