青木です。

今日からプロジェクトの第 2 段階を始めます。
第 2 段階の目標は、メソッドのエントリをすべて揃えることです。
エントリが揃えばいいので、必ずしもドキュメントを書く必要はありません。

== 作業手順

第 2 段階ではテンプレートとして rdoc を使います。

rdoc はソースコードを見てメソッドの存在を判定するので、確実にすべてのメソッドの
エントリが揃っています。そこで、rdoc のデータベースと BitClust のデータベースを
比較して、足りないメソッドを検出します。

rdoc と BitClust のデータベースを比較するツール bc-rdoc.rb を用意しました。メン
バーは bc-rdoc.rb を使って、各ファイルに足りないメソッドを発見し、エントリを書
いてください。

以下、具体的に説明します。

まず、BitClust データベースが必要になるので、以下のコマンドを打って BitClust デ
ータベースをビルドしておいてください。

  ~/c/rubydoc/refm/api $ bitclust -d ./db init
  ~/c/rubydoc/refm/api $ bitclust -d ./db update --stdlibtree=src

それから rdoc データベースも必要です。通常は Ruby をインストールするときに rdoc
も同時にインストールされますが、もし ./configure --disable-install-doc などでオ
フにしている場合は make install-doc しておいてください。

次に、第 1 段階と同じように、レポジトリの ASSIGN ファイルの、「OWNER」欄に自分
のアカウントを書き込んでコミットします。これでそのファイルの排他的編集権を得た
ものとします。

続いて、足りないエントリをチェックします。例えば String クラスをチェックしたい
ときは以下のように打ちます。

  # これは Ruby 1.9 での比較例
  ~/c/rubydoc/refm/api $ bc-rdoc --diff -d ./db String
  + String#<
  + String#<=
  + String#>
  + String#clone
  + String#dup
  + String#each
  + String#to_d
  + String#~
  - String.yaml_new
  - String#_expand_ch
  - String#_regex_quote
  - String#block_scanf
  - String#bytes
  - String#chr
  - String#end_regexp
  - String#end_with?
  - String#expand_ch_hash
  - String#initialize_copy
  - String#is_binary_data?
  - String#is_complex_yaml?
  - String#lines
  - String#ord
  - String#original_succ
  - String#original_succ!
  - String#quote
  - String#rpartition
  - String#start_with?
  - String#to_yaml
  - String#toutf32

すると、このように、BitClust だけにあるメソッドが「+」、 rdoc だけにあるメソッ
ドには「-」が前置されてリストされます。これを見て、足りないメソッドがあることが
わかったら、次のように -c (--content) オプションを追加して実行します。

  ~/c/rubydoc/refm/api $ bc-rdoc --diff -d ./db String -c
  #@# bc-rdoc: detected missing name: bytes
  --- str.bytes   => anEnumerator

  Returns an enumerator that gives each byte in the string.

     "hello".bytes.to_a        #=> [104, 101, 108, 108, 111]

  #@# bc-rdoc: detected missing name: chr
  --- string.chr    ->  string

  Returns a one-character string at the beginning of the string.

     a = "abcde"
     a.chr    #=> "a"

  (以下略)

するとこのように、足りないメソッドの rdoc だけがまとめて出力されます。これを既
存のファイルにリダイレクトなどで追加してください。プロジェクトの第 2 段階ではエ
ントリが揃えばいいので、ドキュメントを書く必要はありません (書きたければ書いて
も構いません)。

なお、このとき、出力されたエントリをすべて追加すべきとは限りません。例えば上記
の例だと、yaml_new や original_succ は追加すべきではありません。 yaml_new は
yaml ライブラリが追加するメソッドなので _builtin/String に書くのは不適切です。
original_succ は (おそらく) jcode ライブラリが一時的に作成する alias で、一
般ユーザが呼び出すことを意図しているとは思えません。

また、特定の Ruby バージョンにしかないメソッドもあります。上記の例では chr,
ord, bytes, lines あたりは Ruby 1.9 にしかありません。メソッドのエントリを追加
するときは、実際の Ruby で挙動を確認しつつ、慎重に追加してください。

この段階では各 Ruby バージョンでの違いを調査する必要があるため、メンバーはでき
る限り 1.8 の全バージョンおよび CVS trunk HEAD をインストールしておいてください。
それが無理なら、最低でも 1.8 の最新リリースバージョンを使ってください。

さて、すべてのエントリを追加しおわったら、まずファイルをコミットします。続いて
ASSIGN ファイルの「STATUS」欄を「done」にして、こちらもコミットします。これで編
集完了です。

== 作業手順のまとめ

 1. 編集するファイルを決める。仮に _builtin/String.rd とする。
 2. ASSIGN ファイルの _builtin/String の「OWNER」欄に自分のアカウントを書き込む
    。
 3. ASSIGN ファイルをコミットする。
 4. bc-rdoc.rb --diff を使って、BitClust データベースに入っていないメソッドをチ
    ェックする。
 5. bc-rdoc.rb --diff -c を使って、BitClust データベースに入っていないメソッド
    を追加する。
 6. _builtin/String.rd を編集する。
 7. _builtin/String.rd をコミットする。
 8. ASSIGN ファイルの _builtin/String の「STATUS」欄に「done」と書き込む。
 9. ASSIGN ファイルをコミットする。


同じ文章が http://doc.loveruby.net/wiki/Phase2WorkingScheme.html
にもあるので随時参照してください。

質問や疑問があったらこの ML で聞いてください。

--
青木峰郎

--
ML: ruby-reference-manual@m...
使い方: http://QuickML.com/