ruby-reference-manual:320

青木です。

予告よりずいぶん遅くなりましたが、第三段階を始めたいと思います。
第三段階の要項を送ります。

# 今後何度か同じメールを繰り返し送る予定です。

== 概要

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

== 締め切り

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

== 作業の手順

さきほど伊達さんにすべてのメソッドエントリに「#@todo」を入 
れて
もらったので、これをすべて消すのが目標です。

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

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

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

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

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

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

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

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

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

[例]

   --- index(pattern, pos = 0)

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

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

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

         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/