青木です。

第三段階の実施要項 rev.3 を送ります。
rev.2 とほとんど変わりません。

== 概要

第三段階では、クラスリファレンスマニュアルの文章をひたすら書きま 
す。
第二段階まででメソッドのエントリと引数は揃っているはずなので、
基本的にそれを信用して書いていきます。ドキュメントの質については
(あまり) 考えなくて構いません。

== 締め切り

第三段階の締め切りは 2007 年 8 月 31 日です。 
この日までにがんばって
すべて書きましょう。6 ヶ月あるわけですが、第三段階はかなり 
手間が
かかるので、これでもけっこう厳しいと予想しています。

== 作業の手順

現在、すべてのメソッドエントリに「#@todo」が入っています。 
これを
すべて消すのが目標です。

作業をするに当たっては、 第 1 段階・第 2 段階 
と同じくライブラリ単位で
担当を分けます。 作業を始めるときは、 まず  
ASSIGN ファイルのうち担当
したいライブラリの行に自分のアカウントを書き込んでコミットします。
これでそのライブラリの担当になったことにします。

次に、担当になったライブラリのドキュメントをひたすら書きます。ライ
ブラリ自体のドキュメント、クラスのドキュメント、メソッドのドキュメ
ントをすべて書いてください。

すでにドキュメントが書いてある場合はそれを活用してください。まだ
ドキュメントが書いていない場合は自分でドキュメントを書いてくださ 
い。

メソッドのドキュメントを書いたら (またはすでに書いてあった 
ら)、その
エントリの「#@todo」を消していきます。一つのライブラリから 
「#@todo」
が完全になくなったら、ASSIGN ファイルの STATUS 欄を 
「done」に変え
てコミットします。 これでそのファイルの作業は完了です。

ドキュメントを書くときは以下のような情報が活用できます。

   1. すでに書いてあるドキュメント
   2. rdoc (ri で出力できる)
   3. ネット上にあるドキュメント
   4. メソッドの実際の挙動
   5. ソースコード
   6. 作者に聞く

ただし、他の人の書いたドキュメントにはそれぞれ著作権があるので、 
その
ままコピペすることは避けてください。 ただし、再利用が可能 
なライセンス
であると明示的に確認できた場合は そのまま使っても構いませ 
ん。それ以外
の場合は参考にするに留めましょう。

なお、このリファレンスマニュアルのライセンスは
http://www.ruby-lang.org/ja/man/?cmd=view;name=%C7%DB%C9%DB%BE%F2%B7%EF
に書かれています。

== メソッドのドキュメントの書きかた

メソッドのドキュメントでは、以下の内容を、この順番で記述します。

   1. メソッドを一言で説明する文を一段落で書く。
       この内容は自動抽出され、「メソッドの要約」として
       クラスのページに出力される。特に内容に注意が必要。
   2. 引数があれば、引数の情報を書く。
     JavaDoc のような形式を使って、
     「@arg pattern 検索するパターン」などと書く。
   3. その他の注意事項を書く。
   4. 使用例を書く。
   5. 発生する例外を書く。
     これも JavaDoc に似せて @raise を使う。
   6. 参照を書く。もしかすると @see を導入するかも。

[例]

   --- index(pattern, pos = 0)

   文字列のうちインデックス pos 以降の部分から
   パターン pattern を検索し、そのインデックスを返します。
   pattern が見付からなかったときは nil を返します。

   @param pattern 検索するパターンです。
   正規表現、文字列、文字コードを示す 0 から 255 の 
整数のいずれかを指定します。

   @param pos 検索を始めるインデックスです。整数で指定します。
   負の数を指定したときは文字列の末尾から数えたインデックスとみ 
なします。

   @raise ArgumentError 上記以外の引数を渡し、
   かつそのオブジェクトが to_s メソッドを持たないときに発 
生します。
         ← メソッドの選択が悪かったのでかなり無理無理な条 
件になってしまった

         p "strstrstr".index(/str/)       # => 0      ←  
引数 pattern の例。よく使うものから順番に
         p "strstrstr".index("str")       # => 0
         p "strstrstr".index(?s)          # => 0

         p "strstrstr".index(/xxx/)       # => nil   ← 検 
索が失敗したときの例。
         p "strstrstr".index("xxx")       # => nil
         p "strstrstr".index(?x)          # => nil

         p "strstrstr".index(/str/, 0)    # => 0    ←  
pos 引数の例。他のパラメータは固定する
         p "strstrstr".index(/str/, 1)    # => 3
         p "strstrstr".index(/str/, 3)    # => 3
         p "strstrstr".index(/str/, 4)    # => 6

         p "strstrstr".index(/str/, -1)   # => nil    ←  
負の pos 引数の例。他のパラメータは固定する
         p "strstrstr".index(/str/, -2)   # => nil
         p "strstrstr".index(/str/, -3)   # => 6

   [[m:String#rindex]] も参照してください。

なお、ファイル全体の記述フォーマットには RDっぽいスタイル 
を使います。
詳しくは Wiki の ClassReferenceManualFormat を参照し 
てください。


以上です。質問などあったらどうぞ。

--
青木峰郎


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