Index: _builtin/IO
===================================================================
--- _builtin/IO	(revision 2581)
+++ _builtin/IO	(working copy)
@@ -460,6 +460,7 @@
 --- select(reads, writes = [], excepts = [], timeout = nil)    -> [[IO]] | nil
 
 [[man:select(2)]] を実行します。
+
 与えられた入力/出力/例外待ちの  IO オブジェクトの中から準備ができたものを
 それぞれ配列にして、配列の配列として返します。
 タイムアウトした時には nil を返します。
@@ -508,12 +509,15 @@
 
 @param path ファイル名を表す文字列を指定します。
 
-@param mode 組み込み関数 [[m:Kernel.#open]] と同じです。
+@param mode モードを文字列か定数の論理和で指定します。
 
-@param perm 組み込み関数 [[m:Kernel.#open]] と同じです。
+@param perm [[man:open(2)]] の第 3 引数のように、ファイルを生成する場合の
+  ファイルのパーミッションを整数で指定します。
 
 @raise Errno::EXXX ファイルのオープンに失敗した場合に発生します。
 
+@see [[m:Kernel.#open]]
+
 #@end
 
 == Instance Methods
@@ -590,13 +594,15 @@
 --- each(rs = $/) {|line| ... }         -> self
 --- each_line(rs = $/) {|line| ... }    -> self
 
-IO の現在位置から 1 行ずつ文字列として読み込み、それを引数として与えられたブロックを実行します。
+IO の現在位置から 1 行ずつ文字列として読み込み、それを引数として
+与えられたブロックを実行します。
 
 #@since 1.9.0
 テキスト読み込みメソッドとして動作します。
 #@end
 
-@param rs 行の区切りを文字列で指定します。rs に nil を指定すると行区切りなしとみなします。空文字列 "" を指定すると連続する改行を行の区切りとみなします(パラグラフモード)。
+@param rs 行の区切りを文字列で指定します。rs に nil を指定すると行区切りなしとみなします。
+          空文字列 "" を指定すると連続する改行を行の区切りとみなします(パラグラフモード)。
 
 @raise IOError 自身が読み込み用にオープンされていなければ発生します。
 
@@ -647,7 +653,10 @@
 
 @param cmd IO に対するコマンドを、添付ライブラリ [[lib:fcntl]] が提供している定数で指定します。
 
-@param arg cmd に対する引数を整数、文字列、booleanのいずれかで指定します。整数の時にはその値を [[man:fcntl(2)]] に渡します。文字列の場合には Array#pack した構造体だとみなして渡します。arg が nil か false の場合には 0を、true の場合には 1 を渡します。
+@param arg cmd に対する引数を整数、文字列、booleanのいずれかで指定します。
+           整数の時にはその値を [[man:fcntl(2)]] に渡します。
+           文字列の場合には Array#pack した構造体だとみなして渡します。
+           arg が nil か false の場合には 0を、true の場合には 1 を渡します。
 
 @raise Errno::EXXX fcntl の実行に失敗した場合に発生します。
 
@@ -731,9 +740,11 @@
 #@since 1.9.0
 テキスト読み込みメソッドとして動作します。
 #@end
-読み込んだ文字列を変数 [[m:$_]] にセットします。[[m:IO#readline]] との違いは EOF での振る舞いのみです。
+読み込んだ文字列を変数 [[m:$_]] にセットします。
+[[m:IO#readline]] との違いは EOF での振る舞いのみです。
 
-@param rs 行の区切りを文字列で指定します。rs に nil を指定すると行区切りなしとみなします。空文字列 "" を指定すると連続する改行を行の区切りとみなします(パラグラフモード)。
+@param rs 行の区切りを文字列で指定します。rs に nil を指定すると行区切りなしとみなします。
+          空文字列 "" を指定すると連続する改行を行の区切りとみなします(パラグラフモード)。
 
 @raise IOError 自身が読み込み用にオープンされていなければ発生します。
 
@@ -752,7 +763,9 @@
 
 @param cmd IO に対するコマンドを整数で指定します。どのようなコマンドが使えるかはプラットフォームに依存します。
 
-@param arg cmd に対する引数を指定します。整数の時にはその値を ioctl に渡します。文字列の場合には [[m:Array#pack]] した構造体だとみなして渡します。arg が nil か false の場合には 0を、true の場合には 1 を渡します。
+@param arg cmd に対する引数を指定します。整数の時にはその値を ioctl に渡します。
+           文字列の場合には [[m:Array#pack]] した構造体だとみなして渡します。
+           arg が nil か false の場合には 0を、true の場合には 1 を渡します。
 
 @raise IOError 既に close されている場合に発生します。
 
@@ -846,6 +859,8 @@
 
 @raise Errno::EXXX 出力に失敗した場合に発生します。
 
+@see [[m:Kernel.#printf]]
+
 --- putc(ch)    -> object
 
 文字 ch を self に出力します。
@@ -858,6 +873,8 @@
 
 @raise Errno::EXXX 出力に失敗した場合に発生します。
 
+@see [[m:Kernel.#putc]]
+
 --- puts(*obj)    -> nil
 
 各 obj を self に出力し、それぞれの後に改行を出力します。
@@ -881,6 +898,8 @@
      nil
      3
 
+@see [[m:Kernel.#puts]]
+
 #@since 1.8.0
 --- read(length = nil, outbuf = "")    -> String | nil
 #@else
@@ -901,7 +920,8 @@
 #@end
 例えば、open(空ファイル) {|f| f.read } は "" となります。
 
-@param length 読み込むサイズを整数で指定します。nil が指定された場合、EOF までの全てのデータを読み込んで、その文字列を返します。
+@param length 読み込むサイズを整数で指定します。
+              nil が指定された場合、EOF までの全てのデータを読み込んで、その文字列を返します。
 
 #@since 1.8.0
 @param outbuf 出力用のバッファを文字列で指定します。IO#read は読み込んだ
@@ -1027,13 +1047,15 @@
 
 @param maxlen 読み込む長さの上限を整数で指定します。
 
-@param outbuf 文字列で指定します。IO#read_nonblock は読み込んだデータを outbuf に破壊的に格納し、返り値は outbuf となります。outbuf は一旦 maxlen 長に拡張(あるいは縮小)されたあと、実際に読み込んだデータのサイズになります。read(2) システムコールが 0 を返した場合は、空文字列になります。
+@param outbuf 文字列で指定します。IO#read_nonblock は読み込んだデータを outbuf に破壊的に格納し、
+              返り値は outbuf となります。outbuf は一旦 maxlen 長に拡張(あるいは縮小)されたあと、
+              実際に読み込んだデータのサイズになります。read(2) システムコールが 0 を返した場合は、空文字列になります。
 
 @raise IOError 自身が読み込み用にオープンされていなければ発生します。
 
 @raise Errno::EXXX read(2) システムコールの結果としてエラーが起きた場合に発生します。
 
-@raise EOFError read(2) システムコールが 0 を返した場合に発生します。 これは、IO が既に EOF に達していることを意味します。
+@raise EOFError read(2) システムコールが 0 を返した場合に発生します。これは、IO が既に EOF に達していることを意味します。
 
 #@end
 
@@ -1125,10 +1147,12 @@
 
 @param path パスを表す文字列を指定します。
 
-@param mode パスを開く際のモードを文字列で指定します。[[m:Kernel.#open]] を参照してください。
+@param mode パスを開く際のモードを文字列で指定します。
 
 @raise Errno::EXXX 失敗した場合に発生します。
 
+@see [[m:Kernel.#open]]
+
 --- rewind    -> 0
 
 ファイルポインタを先頭に移動します。[[m:IO#lineno]] は 0 になります。
@@ -1176,9 +1200,13 @@
 @see [[m:File#lstat]], [[m:File.stat]], [[m:File.lstat]] 
 
 --- sync    -> bool
+
+現在の出力が同期モードならば true を返します。そうでない場合は false を返します。
+
+@raise IOError 既に close されていた場合に発生します。 
+
 --- sync=(newstate)
 
-現在の出力が同期モードならば true を返します。そうでない場合は false を返します。
 自身を同期モードに設定すると、出力関数の呼出毎にバッファがフラッシュされます。
 
 @param newstate 自身を同期モードに設定するかを boolean で指定します。
@@ -1250,15 +1278,21 @@
   }
   # => -:3: warning: sysseek for buffered IO
 
-@param offset [[m:IO#seek]] と同じです。
+@param offset ファイルポインタを移動させるオフセットを整数で指定します。
 
-@param whence  [[m:IO#seek]] と同じです。
+@param whence 値は以下のいずれかです。
 
+  * IO::SEEK_SET: ファイルの先頭から (デフォルト)
+  * IO::SEEK_CUR: 現在のファイルポインタから
+  * IO::SEEK_END: ファイルの末尾から
+
 @raise IOError 読み込み用にバッファリングされた IO に対して実行すると発生します。
                既に close されていた場合にも発生します。 
 
 @raise Errno::EXXX 移動に失敗した場合に発生します。
 
+@see [[m:IO#seek]]
+
 #@end
 
 --- syswrite(string)    -> Integer    
@@ -1376,11 +1410,15 @@
 IO から1バイトを読み込み整数として返します。
 既に EOF に達していれば EOFError が発生します。
 
---- close_on_exec= bool    -> bool
+@raise EOFError 既に EOF に達している場合に発生します。
+
+--- close_on_exec=(bool)    -> bool
 #@todo
 
 自身に close-on-exec フラグを設定します。
 
+@param bool 
+
    f = open("/dev/null")
    f.close_on_exec = true
    system("cat", "/proc/self/fd/#{f.fileno}") # cat: /proc/self/fd/3: No such file or directory