めちゃくちゃ遅い反応ですが、「よく言ってくれた！」という話。
現状のRDocはユーザリファレンスに向いてないと思ってる。
RDoc書いただけで「リファレンスは完璧だお！」とか言ってるやつなんなの - Greenbear Diary (2009-06-04)
以下関係あるようなないような話。わが身は振り返らない方向で。
ダメなマニュアルの特徴
rdoc に限った話ではないですが、以下はダメなマニュアルに共通する特徴だと思います。
- クラスやメソッドを ABC 順に並べている
- メソッドの説明が長い
- サンプルコードがない
こういう文書は読み手を普通のプログラマだと思ってません。
なぜダメか
ABC 順だと、どこから読めばいいかわからない。砂漠の真ん中で迷子になったような気分になります。早く使ってみたいのに使えない歯がゆさ。
説明が長いのは、メソッドの名前が適切でない可能性や、無駄に全機能を列挙しようとしている可能性が高いです。そもそも機能を詰め込みすぎている可能性もあります。
サンプルコードは一番大切です。百聞は一見にしかず。極論すると、サンプルコードさえあればメソッド単位の説明はなくても構いません。サンプルコードでは説明しきれないというなら、そんな API は見直すべきではないか *1 。
ぼくらのような普通のプログラマに必要なのは、そんなボトムアップな説明ではなく、「典型的な使い方がささっとわかる文書」のはずです。
マニュアルは「初めて使うときに読む文書」
ぼくはマニュアルとは「そのライブラリを初めて使うときに読むべき文書」だと考えています *2 。なので、とりあえずの使い方さえわかればよくて、advanced な機能は無理に載せてくれなくてもいいと思っています。
「なんでもいいからとりあえず動かしてから考えたい」というのは性格によるところが大きそうですが、習うより慣れろといいますし、そんなに間違ったことだとは思いません *3 。特に Ruby の場合は、動的型なことと、include や extend やその他いろいろでクラス階層をいじくり倒せるために、使いながらでないと理解しにくいという事情もあるかも。
「リファレンスマニュアルはその名の通り、初心者の導入用文書ではなく、使いなれた人が確認のために参照する文書だ。その場合は上記の特徴が便利だ」という反論は考えられますが、サンプルコード集のような文書でも検索するだけのことですし、Ruby の場合、本当に詳しく知りたい場合はソースを読むものです。
「ソースは実装であって仕様ではないので、それに頼るのは危険だ。文書化された仕様は別途必要だ」という反論は正論です。仕様書を書くのには反対しません。が、仕様書をマニュアル (手引き本、説明書) と呼ぶことはできません。蛇足すると、Ruby のユーザには互換性をそれほど重要視しない人が多い気がしますので、明文化された仕様であっても頼れないかも。
JavaDoc の場合
ダメなマニュアルの特徴を全部満たすのは (Ruby ではないですが) JavaDoc です。ぼくの Java 嫌いの 1/3 くらいはこいつのせいなんですが、このことは JavaDoc の Principle にひとこと書かれていて
At Java Software, we have several guidelines that might make our documentation comments different than those of third party developers. Our documentation comments define the official Java Platform API Specification. To this end, our target audience is those who write Java compatibility tests, or conform or re-implement the Java platform, in addition to developers. We spend time and effort focused on specifying boundary conditions, argument ranges and corner cases rather than defining common programming terms, writing conceptual overviews, and including examples for developers.
Thus, there are commonly two different ways to write doc comments -- as API specifications, or as programming guide documentation. These two targets are described in the following sections. A staff with generous resources can afford to blend both into the same documentation (properly "chunked"); however, our priorities dictate that we give prime focus to writing API specifications in doc comments. This is why developers often need to turn to other documents, such as the J2SE Documentation, Java Tutorial or the Java Class Libraries (in hardback only) for programming guides.
How to Write Doc Comments for the Javadoc Tool
要約すると
- JavaDoc には 2 つの役割がある。1 つは Java プラットフォームを移植・新規開発をする人のための「Java API 仕様書」。もう 1 つは Java でプログラムを書く人向けの「プログラミングガイド」。
- JavaDoc は前者にフォーカスしているので、境界値条件やコーナーケースを書くのに注力している。普通のプログラマは必要に応じて他のドキュメントを参照されたし。
ということで、この文書は普通のプログラマをメインの想定読者としていないのです。だからマニュアルとしてダメなのはしょうがない。実際 Java のあれは「Java Platform, Standard Edition 6 API 仕様」という名前なので、これは仕様書です。嘘いつわりは全くありません。マニュアルがないだけです。
JavaDoc にしても rdoc にしても doc としか言ってないので、それで作っただけで「マニュアル」ができたと思うなってことですね。
どんなのならいいのか
というのにちゃんと答えられないのでダメなんですが、最近ぼくがいいマニュアルだと思ったのは、sequel (DB アクセスライブラリ) のドキュメント。
- http://sequel.rubyforge.org/rdoc/files/doc/cheat_sheet_rdoc.html
- http://sequel.rubyforge.org/rdoc/files/doc/dataset_filtering_rdoc.html
コードで語ってますよね。あーそうか、ぼくの主張は「チートシートをください」というものだ。
