lucille 開発日記: Natural Docs

2003年11月12日

Natural Docs

lucille もそろそろドキュメント周りをちゃんとしなくてはと思い、いくつかドキュメントを書くよいツールを探しています。そこで見つけた Natural Docs について。

Natural Docs は、ソースコードに記述されたコメントを解析して、ソースコードリファレンスのドキュメントを作成するツールです。

Doxygen や Javadoc と同じようなものですが、コメントの書き方はそのまま普通に読めるという特徴があります。また生成される HTML のデザインもシンプルで分りやすいです。

Doxygen や Javadoc では、ドキュメント用のコメントは、タグを使って書かなければならないので、なんか普通にソースコードのコメントの記述を見て理解しようとしても、複雑で何がなんだか分らんという欠点があります。コメントに解読が難しいものを書くのは本末転倒な気がして、lucille では採用してきませんでしたが、Natural Docs だったらいいかなと思います。

Natural Docs では、こんな感じで関数のドキュメントを書く事が出来ます。

/*
 * Function: ri_vector_length
 * 
 *     Calculates the norm of vector in 3D.
 *
 * Parameters:
 *
 *     src - Input vector.
 *
 * Returns:
 *
 *     The norm of vector src in 3D.
 */
RtFloat
ri_vector_length(const ri_vector_t src)
...

ホント普通のコメントと変わらないので、そのままでも読みやすいです。

ちょっといくつかコメントを書いてみて、lucille のソースコードに Natural Docs をかけてみました。

http://web.sfc.keio.ac.jp/~syoyo/lucille/blog/naturaldocs/index.html

いくつか間違って解析されているのもありますが、まあちょっと修正すればよいだけなので問題はないかと思います。

まあしかし、このようなドキュメント化ツールを利用して、ソースコードドキュメントを書くのがホントに役に立つのかどうかは悩みどころです。

コードとドキュメントを一元化できるという利点はありますが、あまり詳しく書くと関数そのものよりもドキュメントのコメントの方が量が多くなったりしたりしてしまいますし、結局個々の関数に対するリファレンスのドキュメントであって全体の設計や流れに対するドキュメントは書けないわけですから。

lrt

個人的に一番よいと思うドキュメント化は、 Knuth の literate プログラミング(文芸的プログラミング) スタイルです。これは Mat Parr 大先生が lrt(literate ray tracer) で採用しています。 lrt は大変参考にしています。てゆうか Mat Parr 大先生の未完の大書 lrt book(最近ではタイトルが The design of a realistic image synthesis system に変わっています) すごすぎです。最高です。すごい勉強になりました。レンダラ書きは必携です。

http://graphics.stanford.edu/courses/cs348b-02/

ソースコードはオフィシャルには配布してないようですが、学生の最終課題のページを探すと入手できます。

投稿者 syoyo : 2003年11月12日 00:40