ruby-reference-manual:156

青木です。

前回のはわかりにくかったようなので、作業方法をより細かくしました。
それから、bc-rdoc.rb の仕様も変わってます。--list とか --diff
がオプションからサブコマンドになりました。


== 作業手順の概要

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

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

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

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

== 前準備

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

  ~/c/rubydoc/refm/api $ bitclust -d ./db init version=1.8.5 encoding=euc-jp
  ~/c/rubydoc/refm/api $ bitclust -d ./db update --stdlibtree=src

それから、できるだけ多くのバージョンの ri データベースを作ります。 1.8.0 ～
1.8.5、それからできれば 1.8 HEAD と CVS trunk HEAD のソースコードをダウンロード
して展開してください (コンパイルする必要はありません)。ここでは、仮に ~/src/
ruby-VERSION (VERSION は 1.8.0 ～ 1.9.0) に展開したとします。

展開が済んだら、以下のコマンドを打って rdoc データベースを作ります。

  ~/c/rubydoc/refm/api $ rdoc --ri --op ris/1.8.0 ~/src/ruby-1.8.0
  ~/c/rubydoc/refm/api $ rdoc --ri --op ris/1.8.1 ~/src/ruby-1.8.1
  ~/c/rubydoc/refm/api $ rdoc --ri --op ris/1.8.2 ~/src/ruby-1.8.2
  ~/c/rubydoc/refm/api $ rdoc --ri --op ris/1.8.3 ~/src/ruby-1.8.3
  ~/c/rubydoc/refm/api $ rdoc --ri --op ris/1.8.4 ~/src/ruby-1.8.4
  ~/c/rubydoc/refm/api $ rdoc --ri --op ris/1.8.5 ~/src/ruby-1.8.5
  ~/c/rubydoc/refm/api $ rdoc --ri --op ris/1.8   ~/src/ruby-1.8     # 1.8 HEAD
  ~/c/rubydoc/refm/api $ rdoc --ri --op ris/1.9.0 ~/src/ruby-1.9.0   # trunk HEAD

シェルの for 文や、バッチファイルを使うと楽に実行できます。

なお、rdoc を実行する ruby のバージョンと rdoc の相性があるようです。とりあえず、
現在の ruby 1.9.0 は rdoc がまともに動きません。 1.8 HEAD もどうも怪しげです。
1.8.4 以上のリリース版を使いましょう。

== リファレンスの編集

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

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

  ~/c/rubydoc/refm/api % bc-rdoc diff --bc=db --ri=ris/1.8.5
  + 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 --bc=./db --ri=ris/1.8.5 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 段階ではエ
ントリが揃えばいいので、ドキュメントを書く必要はありません (書きたければ書いて
も構いません)。

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

== 注意点

bc-rdoc.rb diff で出力されたエントリをすべて追加すべきとは限りません。

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

また、特定の Ruby バージョンにしかないメソッドもあります。上記の例では chr,
ord, bytes, lines あたりは Ruby 1.9 にしかありません。メソッドのエントリを追加
するときは、以上の点に注意する必要があります。

メソッドがいつから存在するのか確認するときにも bc-rdoc.rb が使えます。以下のよ
うに bc-rdoc history コマンドを使うと、指定したクラスの全メソッドについて、どの
バージョンで rdoc が存在するかどうかが一覧できます。

  ~/c/bitclust % ./bin/bc-rdoc.rb history --ri=ris FileUtils
				   180 181 182 183 184 185 190
  FileUtils#cd                       o   o   o   o   o   o   o
  FileUtils#chdir                    o   o   o   o   o   o   o
  FileUtils#chmod                    o   o   o   o   o   o   o
  FileUtils#chmod_R                  -   -   -   o   o   o   o
  FileUtils#chown                    -   -   -   o   o   o   o
  FileUtils#chown_R                  -   -   -   o   o   o   o
  FileUtils#cmp                      o   o   o   o   o   o   o
  FileUtils#compare_file             o   o   o   o   o   o   o
  FileUtils#compare_stream           o   o   o   o   o   o   o
  FileUtils#copy                     o   o   o   o   o   o   o
  FileUtils#copy_entry               -   -   o   o   o   o   o
  FileUtils#copy_file                o   o   o   o   o   o   o
  FileUtils#copy_stream              o   o   o   o   o   o   o
  FileUtils#cp                       o   o   o   o   o   o   o
  FileUtils#cp_r                     o   o   o   o   o   o   o
  FileUtils#fu_have_symlink?         -   -   -   o   o   o   o
  FileUtils#fu_world_writable?       -   -   -   o   o   o   -
  FileUtils#getwd                    o   o   o   o   o   o   o
  FileUtils#identical?               o   o   o   o   o   o   o
  FileUtils#install                  o   o   o   o   o   o   o
  FileUtils#link                     o   o   o   o   o   o   o
  FileUtils#ln                       o   o   o   o   o   o   o
  FileUtils#ln_s                     o   o   o   o   o   o   o
  FileUtils#ln_sf                    o   o   o   o   o   o   o
  FileUtils#makedirs                 o   o   o   o   o   o   o
  FileUtils#mkdir                    o   o   o   o   o   o   o
  FileUtils#mkdir_p                  o   o   o   o   o   o   o
  FileUtils#mkpath                   o   o   o   o   o   o   o
  FileUtils#move                     o   o   o   o   o   o   o
  FileUtils#mv                       o   o   o   o   o   o   o
  FileUtils#pwd                      o   o   o   o   o   o   o
  FileUtils#remove                   o   o   o   o   o   o   o
  FileUtils#remove_dir               -   -   -   o   o   o   o
  FileUtils#remove_entry             -   -   -   o   o   o   o
  FileUtils#remove_entry_secure      -   -   -   o   o   o   o
  FileUtils#remove_file              -   -   -   o   o   o   o
  FileUtils#rm                       o   o   o   o   o   o   o
  FileUtils#rm_f                     o   o   o   o   o   o   o
  FileUtils#rm_r                     o   o   o   o   o   o   o
  FileUtils#rm_rf                    o   o   o   o   o   o   o
  FileUtils#rmdir                    o   o   o   o   o   o   o
  FileUtils#rmtree                   o   o   o   o   o   o   o
  FileUtils#safe_unlink              o   o   o   o   o   o   o
  FileUtils#symlink                  o   o   o   o   o   o   o
  FileUtils#touch                    o   o   o   o   o   o   o
  FileUtils#uptodate?                o   o   o   o   o   o   o

「o」が表示されているバージョンには rdoc が存在し、「-」と表示されているバージ
ョンには rdoc が存在しないことを示します。
ただし、このコマンドもあくまでも「rdoc があるかどうか」を示しているだけで、その
メソッドが本当に存在するかどうかはわかりません。特に 1.8.0 と 1.8.1 の rdoc は
非常に怪しいので、あまり信用しないほうがいいでしょう。

どのバージョンから追加されたのかわからないときは……

いろいろ書きましたが、この段階で一番重要なのは、次の安定版リリースである 1.8.6
のメソッドをきっちり揃えることです。「そのメソッドがいつ追加されたか」というの
は追加的な情報にすぎません。どのバージョンから追加されたのかよくわからないとき
は、「#@# 追加されたバージョンは不明」とでもコメントを書いておいて、次のファイ
ルに進みましょう。たぶんそのうち誰かが調べます。

作業手順のまとめ

 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: ruby-reference-manual@m...
使い方: http://QuickML.com/