[DOC] fix markups [ci skip]

git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@67337 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

1 files changed, 160 insertions, 174 deletions

diff --git a/io.c b/io.c
index 8cbe34706c..cd83f520af 100644
--- a/io.c
+++ b/io.c
@@ -2003,7 +2003,7 @@ static void clear_readconv(rb_io_t *fptr);
  *     ios.rewind    -> 0
  *
  *  Positions <em>ios</em> to the beginning of input, resetting
- *  <code>lineno</code> to zero.
+ *  #lineno to zero.
  *
  *     f = File.new("testfile")
  *     f.readline   #=> "This is line one\n"
@@ -2089,14 +2089,14 @@ io_fillbuf(rb_io_t *fptr)
  *
  *  Returns true if <em>ios</em> is at end of file that means
  *  there are no more data to read.
- *  The stream must be opened for reading or an <code>IOError</code> will be
+ *  The stream must be opened for reading or an IOError will be
  *  raised.
  *
  *     f = File.new("testfile")
  *     dummy = f.readlines
  *     f.eof   #=> true
  *
- *  If <em>ios</em> is a stream such as pipe or socket, <code>IO#eof?</code>
+ *  If <em>ios</em> is a stream such as pipe or socket, IO#eof?
  *  blocks until the other end sends some data or closes it.
  *
  *     r, w = IO.pipe
@@ -2110,10 +2110,9 @@ io_fillbuf(rb_io_t *fptr)
  *     r, w = IO.pipe
  *     r.eof?  # blocks forever
  *
- *  Note that <code>IO#eof?</code> reads data to the input byte buffer.
- *  So <code>IO#sysread</code> may not behave as you intend with
- *  <code>IO#eof?</code>, unless you call <code>IO#rewind</code>
- *  first (which is not available for some streams).
+ *  Note that IO#eof? reads data to the input byte buffer.  So
+ *  IO#sysread may not behave as you intend with IO#eof?, unless you
+ *  call IO#rewind first (which is not available for some streams).
  */
 
 VALUE
@@ -2145,7 +2144,7 @@ rb_io_eof(VALUE io)
  *  Returns the current ``sync mode'' of <em>ios</em>. When sync mode is
  *  true, all output is immediately flushed to the underlying operating
  *  system and is not buffered by Ruby internally. See also
- *  <code>IO#fsync</code>.
+ *  IO#fsync.
  *
  *     f = File.new("testfile")
  *     f.sync   #=> false
@@ -2170,7 +2169,7 @@ rb_io_sync(VALUE io)
  *  Sets the ``sync mode'' to <code>true</code> or <code>false</code>.
  *  When sync mode is true, all output is immediately flushed to the
  *  underlying operating system and is not buffered internally. Returns
- *  the new state. See also <code>IO#fsync</code>.
+ *  the new state. See also IO#fsync.
  *
  *     f = File.new("testfile")
  *     f.sync = true
@@ -2197,12 +2196,11 @@ rb_io_set_sync(VALUE io, VALUE sync)
  *     ios.fsync   -> 0 or nil
  *
  *  Immediately writes all buffered data in <em>ios</em> to disk.
- *  Note that <code>fsync</code> differs from
- *  using <code>IO#sync=</code>. The latter ensures that data is flushed
- *  from Ruby's buffers, but does not guarantee that the underlying
- *  operating system actually writes it to disk.
+ *  Note that #fsync differs from using IO#sync=. The latter ensures
+ *  that data is flushed from Ruby's buffers, but does not guarantee
+ *  that the underlying operating system actually writes it to disk.
  *
- *  <code>NotImplementedError</code> is raised
+ *  NotImplementedError is raised
  *  if the underlying operating system does not support <em>fsync(2)</em>.
  */
 
@@ -2251,8 +2249,8 @@ nogvl_fdatasync(void *ptr)
  *  Immediately writes all buffered data in <em>ios</em> to disk.
  *
  *  If the underlying operating system does not support <em>fdatasync(2)</em>,
- *  <code>IO#fsync</code> is called instead (which might raise a
- *  <code>NotImplementedError</code>).
+ *  IO#fsync is called instead (which might raise a
+ *  NotImplementedError).
  */
 
 static VALUE
@@ -2305,7 +2303,7 @@ rb_io_fileno(VALUE io)
  *     ios.pid    -> integer
  *
  *  Returns the process ID of a child process associated with
- *  <em>ios</em>. This will be set by <code>IO.popen</code>.
+ *  <em>ios</em>. This will be set by IO.popen.
  *
  *     pipe = IO.popen("-")
  *     if pipe
@@ -2868,7 +2866,7 @@ io_getpartial(int argc, VALUE *argv, VALUE io, VALUE opts, int nonblock)
  *  The _outbuf_ will contain only the received data after the method call
  *  even if it is not empty at the beginning.
  *
- *  It raises <code>EOFError</code> on end of file.
+ *  It raises EOFError on end of file.
  *
  *  readpartial is designed for streams such as pipe, socket, tty, etc.
  *  It blocks only when no data immediately available.
@@ -3581,12 +3579,12 @@ rb_io_gets_internal(VALUE io)
  *  <i>sep</i>. A separator of +nil+ reads the entire
  *  contents, and a zero-length separator reads the input a paragraph at
  *  a time (two successive newlines in the input separate paragraphs).
- *  The stream must be opened for reading or an <code>IOError</code>
- *  will be raised. The line read in will be returned and also assigned
- *  to <code>$_</code>. Returns +nil+ if called at end of
- *  file.  If the first argument is an integer, or optional second
- *  argument is given, the returning string would not be longer than the
- *  given value in bytes.
+ *  The stream must be opened for reading or an IOError will be raised.
+ *  The line read in will be returned and also assigned to
+ *  <code>$_</code>. Returns +nil+ if called at end of file.  If the
+ *  first argument is an integer, or optional second argument is given,
+ *  the returning string would not be longer than the given value in
+ *  bytes.
  *
  *     File.new("testfile").gets   #=> "This is line one\n"
  *     $_                          #=> "This is line one\n"
@@ -3620,12 +3618,12 @@ rb_io_gets_m(int argc, VALUE *argv, VALUE io)
  *     ios.lineno    -> integer
  *
  *  Returns the current line number in <em>ios</em>.  The stream must be
- *  opened for reading. <code>lineno</code> counts the number of times
- *  #gets is called rather than the number of newlines encountered.  The two
- *  values will differ if #gets is called with a separator other than newline.
+ *  opened for reading. #lineno counts the number of times #gets is called
+ *  rather than the number of newlines encountered.  The two values will
+ *  differ if #gets is called with a separator other than newline.
  *
  *  Methods that use <code>$/</code> like #each, #lines and #readline will
- *  also increment <code>lineno</code>.
+ *  also increment #lineno.
  *
  *  See also the <code>$.</code> variable.
  *
@@ -3681,8 +3679,7 @@ rb_io_set_lineno(VALUE io, VALUE lineno)
  *     ios.readline(limit [, getline_args])      -> string
  *     ios.readline(sep, limit [, getline_args]) -> string
  *
- *  Reads a line as with <code>IO#gets</code>, but raises an
- *  <code>EOFError</code> on end of file.
+ *  Reads a line as with IO#gets, but raises an EOFError on end of file.
  */
 
 static VALUE
@@ -3711,7 +3708,7 @@ static VALUE io_readlines(const struct getline_arg *arg, VALUE io);
  *  If the first argument is an integer, or an
  *  optional second argument is given, the returning string would not be
  *  longer than the given value in bytes. The stream must be opened for
- *  reading or an <code>IOError</code> will be raised.
+ *  reading or an IOError will be raised.
  *
  *     f = File.new("testfile")
  *     f.readlines[0]   #=> "This is line one\n"
@@ -3759,7 +3756,7 @@ io_readlines(const struct getline_arg *arg, VALUE io)
  *
  *  Executes the block for every line in <em>ios</em>, where lines are
  *  separated by <i>sep</i>. <em>ios</em> must be opened for
- *  reading or an <code>IOError</code> will be raised.
+ *  reading or an IOError will be raised.
  *
  *  If no block is given, an enumerator is returned instead.
  *
@@ -3793,7 +3790,7 @@ rb_io_each_line(int argc, VALUE *argv, VALUE io)
 }
 
 /*
- *  This is a deprecated alias for <code>each_line</code>.
+ *  This is a deprecated alias for #each_line.
  */
 
 static VALUE
@@ -3812,7 +3809,7 @@ rb_io_lines(int argc, VALUE *argv, VALUE io)
  *
  *  Calls the given block once for each byte (0..255) in <em>ios</em>,
  *  passing the byte as an argument. The stream must be opened for
- *  reading or an <code>IOError</code> will be raised.
+ *  reading or an IOError will be raised.
  *
  *  If no block is given, an enumerator is returned instead.
  *
@@ -3844,7 +3841,7 @@ rb_io_each_byte(VALUE io)
 }
 
 /*
- *  This is a deprecated alias for <code>each_byte</code>.
+ *  This is a deprecated alias for #each_byte.
  */
 
 static VALUE
@@ -3970,7 +3967,7 @@ io_getc(rb_io_t *fptr, rb_encoding *enc)
  *
  *  Calls the given block once for each character in <em>ios</em>,
  *  passing the character as an argument. The stream must be opened for
- *  reading or an <code>IOError</code> will be raised.
+ *  reading or an IOError will be raised.
  *
  *  If no block is given, an enumerator is returned instead.
  *
@@ -3998,7 +3995,7 @@ rb_io_each_char(VALUE io)
 }
 
 /*
- *  This is a deprecated alias for <code>each_char</code>.
+ *  This is a deprecated alias for #each_char.
  */
 
 static VALUE
@@ -4018,9 +4015,9 @@ rb_io_chars(VALUE io)
  *     ios.each_codepoint               -> an_enumerator
  *     ios.codepoints                   -> an_enumerator
  *
- *  Passes the <code>Integer</code> ordinal of each character in <i>ios</i>,
+ *  Passes the Integer ordinal of each character in <i>ios</i>,
  *  passing the codepoint as an argument. The stream must be opened for
- *  reading or an <code>IOError</code> will be raised.
+ *  reading or an IOError will be raised.
  *
  *  If no block is given, an enumerator is returned instead.
  *
@@ -4126,7 +4123,7 @@ rb_io_each_codepoint(VALUE io)
 }
 
 /*
- *  This is a deprecated alias for <code>each_codepoint</code>.
+ *  This is a deprecated alias for #each_codepoint.
  */
 
 static VALUE
@@ -4170,7 +4167,7 @@ rb_io_getc(VALUE io)
  *     ios.readchar   -> string
  *
  *  Reads a one-character string from <em>ios</em>. Raises an
- *  <code>EOFError</code> on end of file.
+ *  EOFError on end of file.
  *
  *     f = File.new("testfile")
  *     f.readchar   #=> "h"
@@ -4229,8 +4226,8 @@ rb_io_getbyte(VALUE io)
  *  call-seq:
  *     ios.readbyte   -> integer
  *
- *  Reads a byte as with <code>IO#getbyte</code>, but raises an
- *  <code>EOFError</code> on end of file.
+ *  Reads a byte as with IO#getbyte, but raises an EOFError on end of
+ *  file.
  */
 
 static VALUE
@@ -4253,7 +4250,7 @@ rb_io_readbyte(VALUE io)
  *  such that a subsequent buffered read will return it. Only one byte
  *  may be pushed back before a subsequent read operation (that is,
  *  you will be able to read only the last of several bytes that have been pushed
- *  back). Has no effect with unbuffered reads (such as <code>IO#sysread</code>).
+ *  back). Has no effect with unbuffered reads (such as IO#sysread).
  *
  *     f = File.new("testfile")   #=> #<File:testfile>
  *     b = f.getbyte              #=> 0x38
@@ -4292,7 +4289,7 @@ rb_io_ungetbyte(VALUE io, VALUE b)
  *  such that a subsequent buffered character read will return it. Only one character
  *  may be pushed back before a subsequent read operation (that is,
  *  you will be able to read only the last of several characters that have been pushed
- *  back). Has no effect with unbuffered reads (such as <code>IO#sysread</code>).
+ *  back). Has no effect with unbuffered reads (such as IO#sysread).
  *
  *     f = File.new("testfile")   #=> #<File:testfile>
  *     c = f.getc                 #=> "8"
@@ -4819,12 +4816,11 @@ rb_io_close(VALUE io)
  *
  *  Closes <em>ios</em> and flushes any pending writes to the operating
  *  system. The stream is unavailable for any further data operations;
- *  an <code>IOError</code> is raised if such an attempt is made. I/O
- *  streams are automatically closed when they are claimed by the
- *  garbage collector.
+ *  an IOError is raised if such an attempt is made. I/O streams are
+ *  automatically closed when they are claimed by the garbage collector.
  *
- *  If <em>ios</em> is opened by <code>IO.popen</code>,
- *  <code>close</code> sets <code>$?</code>.
+ *  If <em>ios</em> is opened by IO.popen, #close sets
+ *  <code>$?</code>.
  *
  *  Calling this method on closed IO object is just ignored since Ruby 2.3.
  */
@@ -4914,7 +4910,7 @@ rb_io_closed(VALUE io)
  *
  *  Closes the read end of a duplex I/O stream (i.e., one that contains
  *  both a read and a write stream, such as a pipe). Will raise an
- *  <code>IOError</code> if the stream is not duplexed.
+ *  IOError if the stream is not duplexed.
  *
  *     f = IO.popen("/bin/sh","r+")
  *     f.close_read
@@ -4975,7 +4971,7 @@ rb_io_close_read(VALUE io)
  *
  *  Closes the write end of a duplex I/O stream (i.e., one that contains
  *  both a read and a write stream, such as a pipe). Will raise an
- *  <code>IOError</code> if the stream is not duplexed.
+ *  IOError if the stream is not duplexed.
  *
  *     f = IO.popen("/bin/sh","r+")
  *     f.close_write
@@ -5028,8 +5024,8 @@ rb_io_close_write(VALUE io)
  *     ios.sysseek(offset, whence=IO::SEEK_SET)   -> integer
  *
  *  Seeks to a given <i>offset</i> in the stream according to the value
- *  of <i>whence</i> (see <code>IO#seek</code> for values of
- *  <i>whence</i>). Returns the new offset into the file.
+ *  of <i>whence</i> (see IO#seek for values of <i>whence</i>). Returns
+ *  the new offset into the file.
  *
  *     f = File.new("testfile")
  *     f.sysseek(-13, IO::SEEK_END)   #=> 53
@@ -5070,7 +5066,7 @@ rb_io_sysseek(int argc, VALUE *argv, VALUE io)
  *  Writes the given string to <em>ios</em> using a low-level write.
  *  Returns the number of bytes written. Do not mix with other methods
  *  that write to <em>ios</em> or you may get unpredictable results.
- *  Raises <code>SystemCallError</code> on error.
+ *  Raises SystemCallError on error.
  *
  *     f = File.new("out", "w")
  *     f.syswrite("ABCDEF")   #=> 6
@@ -5117,8 +5113,7 @@ rb_io_syswrite(VALUE io, VALUE str)
  *  The _outbuf_ will contain only the received data after the method call
  *  even if it is not empty at the beginning.
  *
- *  Raises <code>SystemCallError</code> on error and
- *  <code>EOFError</code> at end of file.
+ *  Raises SystemCallError on error and EOFError at end of file.
  *
  *     f = File.new("testfile")
  *     f.sysread(16)   #=> "This is line one"
@@ -5212,9 +5207,8 @@ pread_internal_call(VALUE arg)
  *  This bypasses any userspace buffering of the IO layer.
  *  If the optional <i>outbuf</i> argument is present, it must
  *  reference a String, which will receive the data.
- *  Raises <code>SystemCallError</code> on error, <code>EOFError</code>
- *  at end of file and <code>NotImplementedError</code> if platform does not
- *  implement the system call.
+ *  Raises SystemCallError on error, EOFError at end of file and
+ *  NotImplementedError if platform does not implement the system call.
  *
  *     File.write("testfile", "This is line one\nThis is line two\n")
  *     File.open("testfile") do |f|
@@ -5283,7 +5277,7 @@ internal_pwrite_func(void *ptr)
  *  same IO object for reading the file at various locations.
  *  This bypasses any userspace buffering of the IO layer.
  *  Returns the number of bytes written.
- *  Raises <code>SystemCallError</code> on error and <code>NotImplementedError</code>
+ *  Raises SystemCallError on error and NotImplementedError
  *  if platform does not implement the system call.
  *
  *     File.open("out", "w") do |f|
@@ -6795,7 +6789,7 @@ pipe_close(VALUE io)
  *
  *  Runs the specified command as a subprocess; the subprocess's
  *  standard input and output will be connected to the returned
- *  <code>IO</code> object.
+ *  IO object.
  *
  *  The PID of the started process can be obtained by IO#pid method.
  *
@@ -6814,7 +6808,7 @@ pipe_close(VALUE io)
  *  If <i>cmd</i> is an +Array+ of +String+,
  *  then it will be used as the subprocess's +argv+ bypassing a shell.
  *  The array can contain a hash at first for environments and
- *  a hash at last for options similar to <code>spawn</code>.
+ *  a hash at last for options similar to #spawn.
  *
  *  The default mode for the new file object is ``r'',
  *  but <i>mode</i> may be set to any of the modes listed in the description for class IO.
@@ -6836,15 +6830,13 @@ pipe_close(VALUE io)
  *      ls_result_with_error = ls_io.read
  *    }
  *
- *  Raises exceptions which <code>IO.pipe</code> and
- *  <code>Kernel.spawn</code> raise.
+ *  Raises exceptions which IO.pipe and Kernel.spawn raise.
  *
  *  If a block is given, Ruby will run the command as a child connected
  *  to Ruby with a pipe. Ruby's end of the pipe will be passed as a
  *  parameter to the block.
  *  At the end of block, Ruby closes the pipe and sets <code>$?</code>.
- *  In this case <code>IO.popen</code> returns
- *  the value of the block.
+ *  In this case IO.popen returns the value of the block.
  *
  *  If a block is given with a _cmd_ of ``<code>-</code>'',
  *  the block will be run in two separate processes: once in the parent,
@@ -6989,11 +6981,11 @@ rb_open_file(int argc, const VALUE *argv, VALUE io)
  *     File.open(filename, mode="r" [, opt]) {|file| block } -> obj
  *     File.open(filename [, mode [, perm]] [, opt]) {|file| block } -> obj
  *
- *  With no associated block, <code>File.open</code> is a synonym for
+ *  With no associated block, File.open is a synonym for
  *  File.new. If the optional code block is given, it will
  *  be passed the opened +file+ as an argument and the File object will
  *  automatically be closed when the block terminates.  The value of the block
- *  will be returned from <code>File.open</code>.
+ *  will be returned from File.open.
  *
  *  If a file is being created, its initial permissions may be set using the
  *  +perm+ parameter.  See File.new for further discussion.
@@ -7008,7 +7000,7 @@ rb_open_file(int argc, const VALUE *argv, VALUE io)
  *     IO.open(fd, mode="r" [, opt])                -> io
  *     IO.open(fd, mode="r" [, opt]) {|io| block }  -> obj
  *
- *  With no associated block, <code>IO.open</code> is a synonym for IO.new.  If
+ *  With no associated block, IO.open is a synonym for IO.new.  If
  *  the optional code block is given, it will be passed +io+ as an argument,
  *  and the IO object will automatically be closed when the block terminates.
  *  In this instance, IO.open returns the value of the block.
@@ -7033,7 +7025,7 @@ rb_io_s_open(int argc, VALUE *argv, VALUE klass)
  *     IO.sysopen(path, [mode, [perm]])  -> integer
  *
  *  Opens the given path, returning the underlying file descriptor as a
- *  <code>Integer</code>.
+ *  Integer.
  *
  *     IO.sysopen("testfile")   #=> 3
  */
@@ -7493,8 +7485,7 @@ rb_io_init_copy(VALUE dest, VALUE io)
  *     ios.printf(format_string [, obj, ...])   -> nil
  *
  *  Formats and writes to <em>ios</em>, converting parameters under
- *  control of the format string. See <code>Kernel#sprintf</code>
- *  for details.
+ *  control of the format string. See Kernel#sprintf for details.
  */
 
 VALUE
@@ -7617,11 +7608,10 @@ rb_f_print(int argc, const VALUE *argv)
  *  call-seq:
  *     ios.putc(obj)    -> obj
  *
- *  If <i>obj</i> is <code>Numeric</code>, write the character whose code is
- *  the least-significant byte of <i>obj</i>.
- *  If <i>obj</i> is <code>String</code>, write the first character
- *  of <i>obj</i> to <em>ios</em>.
- *  Otherwise, raise <code>TypeError</code>.
+ *  If <i>obj</i> is Numeric, write the character whose code is the
+ *  least-significant byte of <i>obj</i>.  If <i>obj</i> is String,
+ *  write the first character of <i>obj</i> to <em>ios</em>.  Otherwise,
+ *  raise TypeError.
  *
  *     $stdout.putc "A"
  *     $stdout.putc 65
@@ -8138,8 +8128,8 @@ rb_io_make_open_file(VALUE obj)
  *  	"t"  Text file mode
  *
  *  The exclusive access mode ("x") can be used together with "w" to ensure
- *  the file is created. <code>Errno::EEXIST</code> is raised when it already
- *  exists. It may not be supported with all kinds of streams (e.g. pipes).
+ *  the file is created. Errno::EEXIST is raised when it already exists.
+ *  It may not be supported with all kinds of streams (e.g. pipes).
  *
  *  When the open mode of original IO is read only, the mode cannot be
  *  changed to be writable.  Similarly, the open mode cannot be changed from
@@ -8229,7 +8219,7 @@ rb_io_make_open_file(VALUE obj)
  *    io.puts "Hello, World!"
  *
  *  Both of above print "Hello, World!" in UTF-16LE to standard error output
- *  with converting EOL generated by <code>puts</code> to CR.
+ *  with converting EOL generated by #puts to CR.
  */
 
 static VALUE
@@ -8307,8 +8297,7 @@ rb_io_initialize(int argc, VALUE *argv, VALUE io)
  *
  *  The new File object is buffered mode (or non-sync mode), unless
  *  +filename+ is a tty.
- *  See IO#flush, IO#fsync, IO#fdatasync, and <code>IO#sync=</code>
- *  about sync mode.
+ *  See IO#flush, IO#fsync, IO#fdatasync, and IO#sync= about sync mode.
  *
  *  === Examples
  *
@@ -8354,7 +8343,7 @@ rb_io_s_new(int argc, VALUE *argv, VALUE klass)
  *  call-seq:
  *     IO.for_fd(fd, mode [, opt])    -> io
  *
- *  Synonym for <code>IO.new</code>.
+ *  Synonym for IO.new.
  *
  */
 
@@ -8882,7 +8871,7 @@ static VALUE argf_readline(int, VALUE *, VALUE);
  *     readline(limit)      -> string
  *     readline(sep, limit) -> string
  *
- *  Equivalent to <code>Kernel::gets</code>, except
+ *  Equivalent to Kernel::gets, except
  *  +readline+ raises +EOFError+ at end of file.
  */
 
@@ -9314,17 +9303,17 @@ advice_arg_check(VALUE advice)
  *
  *  If an error occurs, one of the following exceptions will be raised:
  *
- *  <code>IOError</code>:: The <code>IO</code> stream is closed.
- *  <code>Errno::EBADF</code>::
+ *  IOError:: The IO stream is closed.
+ *  Errno::EBADF::
  *    The file descriptor of the current file is invalid.
- *  <code>Errno::EINVAL</code>:: An invalid value for _advice_ was given.
- *  <code>Errno::ESPIPE</code>::
+ *  Errno::EINVAL:: An invalid value for _advice_ was given.
+ *  Errno::ESPIPE::
  *    The file descriptor of the current file refers to a FIFO or
- *    pipe. (Linux raises <code>Errno::EINVAL</code> in this case).
- *  <code>TypeError</code>::
+ *    pipe. (Linux raises Errno::EINVAL in this case).
+ *  TypeError::
  *    Either _advice_ was not a Symbol, or one of the
- *    other arguments was not an <code>Integer</code>.
- *  <code>RangeError</code>:: One of the arguments given was too big/small.
+ *    other arguments was not an Integer.
+ *  RangeError:: One of the arguments given was too big/small.
  *
  *  This list is not exhaustive; other Errno:: exceptions are also possible.
  */
@@ -9357,29 +9346,28 @@ rb_io_advise(int argc, VALUE *argv, VALUE io)
  *     IO.select(read_array [, write_array [, error_array [, timeout]]]) -> array or nil
  *
  *  Calls select(2) system call.
- *  It monitors given arrays of <code>IO</code> objects, waits until one or more
- *  of <code>IO</code> objects are ready for reading, are ready for writing,
- *  and have pending exceptions respectively, and returns an array that
- *  contains arrays of those IO objects.  It will return +nil+
- *  if optional <i>timeout</i> value is given and no <code>IO</code> object
- *  is ready in <i>timeout</i> seconds.
- *
- *  <code>IO.select</code> peeks the buffer of <code>IO</code> objects for testing readability.
- *  If the <code>IO</code> buffer is not empty,
- *  <code>IO.select</code> immediately notifies readability.
- *  This "peek" only happens for <code>IO</code> objects.
- *  It does not happen for IO-like objects such as OpenSSL::SSL::SSLSocket.
- *
- *  The best way to use <code>IO.select</code> is invoking it
- *  after nonblocking methods such as <code>read_nonblock</code>, <code>write_nonblock</code>, etc.
- *  The methods raise an exception which is extended by
- *  <code>IO::WaitReadable</code> or <code>IO::WaitWritable</code>.
- *  The modules notify how the caller should wait with <code>IO.select</code>.
- *  If <code>IO::WaitReadable</code> is raised, the caller should wait for reading.
- *  If <code>IO::WaitWritable</code> is raised, the caller should wait for writing.
- *
- *  So, blocking read (<code>readpartial</code>) can be emulated using
- *  <code>read_nonblock</code> and <code>IO.select</code> as follows:
+ *  It monitors given arrays of IO objects, waits until one or more of
+ *  IO objects are ready for reading, are ready for writing, and have
+ *  pending exceptions respectively, and returns an array that contains
+ *  arrays of those IO objects.  It will return +nil+ if optional
+ *  <i>timeout</i> value is given and no IO object is ready in
+ *  <i>timeout</i> seconds.
+ *
+ *  IO.select peeks the buffer of IO objects for testing readability.
+ *  If the IO buffer is not empty, IO.select immediately notifies
+ *  readability.  This "peek" only happens for IO objects.  It does not
+ *  happen for IO-like objects such as OpenSSL::SSL::SSLSocket.
+ *
+ *  The best way to use IO.select is invoking it after nonblocking
+ *  methods such as #read_nonblock, #write_nonblock, etc.  The methods
+ *  raise an exception which is extended by IO::WaitReadable or
+ *  IO::WaitWritable.  The modules notify how the caller should wait
+ *  with IO.select.  If IO::WaitReadable is raised, the caller should
+ *  wait for reading.  If IO::WaitWritable is raised, the caller should
+ *  wait for writing.
+ *
+ *  So, blocking read (#readpartial) can be emulated using
+ *  #read_nonblock and IO.select as follows:
  *
  *    begin
  *      result = io_like.read_nonblock(maxlen)
@@ -9391,57 +9379,57 @@ rb_io_advise(int argc, VALUE *argv, VALUE io)
  *      retry
  *    end
  *
- *  Especially, the combination of nonblocking methods and
- *  <code>IO.select</code> is preferred for <code>IO</code> like
- *  objects such as <code>OpenSSL::SSL::SSLSocket</code>.
- *  It has <code>to_io</code> method to return underlying <code>IO</code> object.
- *  <code>IO.select</code> calls <code>to_io</code> to obtain the file descriptor to wait.
+ *  Especially, the combination of nonblocking methods and IO.select is
+ *  preferred for IO like objects such as OpenSSL::SSL::SSLSocket.  It
+ *  has #to_io method to return underlying IO object.  IO.select calls
+ *  #to_io to obtain the file descriptor to wait.
  *
- *  This means that readability notified by <code>IO.select</code> doesn't mean
- *  readability from <code>OpenSSL::SSL::SSLSocket</code> object.
+ *  This means that readability notified by IO.select doesn't mean
+ *  readability from OpenSSL::SSL::SSLSocket object.
  *
- *  The most likely situation is that <code>OpenSSL::SSL::SSLSocket</code> buffers some data.
- *  <code>IO.select</code> doesn't see the buffer.
- *  So <code>IO.select</code> can block when <code>OpenSSL::SSL::SSLSocket#readpartial</code> doesn't block.
+ *  The most likely situation is that OpenSSL::SSL::SSLSocket buffers
+ *  some data.  IO.select doesn't see the buffer.  So IO.select can
+ *  block when OpenSSL::SSL::SSLSocket#readpartial doesn't block.
  *
  *  However, several more complicated situations exist.
  *
  *  SSL is a protocol which is sequence of records.
  *  The record consists of multiple bytes.
- *  So, the remote side of SSL sends a partial record,
- *  <code>IO.select</code> notifies readability but
- *  <code>OpenSSL::SSL::SSLSocket</code> cannot decrypt a byte and
- *  <code>OpenSSL::SSL::SSLSocket#readpartial</code> will block.
+ *  So, the remote side of SSL sends a partial record, IO.select
+ *  notifies readability but OpenSSL::SSL::SSLSocket cannot decrypt a
+ *  byte and OpenSSL::SSL::SSLSocket#readpartial will block.
  *
  *  Also, the remote side can request SSL renegotiation which forces
  *  the local SSL engine to write some data.
- *  This means <code>OpenSSL::SSL::SSLSocket#readpartial</code> may
- *  invoke <code>write</code> system call and it can block.
- *  In such a situation, <code>OpenSSL::SSL::SSLSocket#read_nonblock</code>
- *  raises IO::WaitWritable instead of blocking.
- *  So, the caller should wait for ready for writability as above example.
+ *  This means OpenSSL::SSL::SSLSocket#readpartial may invoke #write
+ *  system call and it can block.
+ *  In such a situation, OpenSSL::SSL::SSLSocket#read_nonblock raises
+ *  IO::WaitWritable instead of blocking.
+ *  So, the caller should wait for ready for writability as above
+ *  example.
  *
- *  The combination of nonblocking methods and <code>IO.select</code> is
- *  also useful for streams such as tty, pipe socket socket when
- *  multiple processes read from a stream.
+ *  The combination of nonblocking methods and IO.select is also useful
+ *  for streams such as tty, pipe socket socket when multiple processes
+ *  read from a stream.
  *
  *  Finally, Linux kernel developers don't guarantee that
  *  readability of select(2) means readability of following read(2) even
  *  for a single process.
  *  See select(2) manual on GNU/Linux system.
  *
- *  Invoking <code>IO.select</code> before <code>IO#readpartial</code> works well as usual.
- *  However it is not the best way to use <code>IO.select</code>.
+ *  Invoking IO.select before IO#readpartial works well as usual.
+ *  However it is not the best way to use IO.select.
  *
  *  The writability notified by select(2) doesn't show
  *  how many bytes are writable.
- *  <code>IO#write</code> method blocks until given whole string is written.
- *  So, <code>IO#write(two or more bytes)</code> can block after writability is notified by <code>IO.select</code>.
- *  <code>IO#write_nonblock</code> is required to avoid the blocking.
+ *  IO#write method blocks until given whole string is written.
+ *  So, <code>IO#write(two or more bytes)</code> can block after
+ *  writability is notified by IO.select.  IO#write_nonblock is required
+ *  to avoid the blocking.
  *
- *  Blocking write (<code>write</code>) can be emulated using
- *  <code>write_nonblock</code> and <code>IO.select</code> as follows:
- *  IO::WaitReadable should also be rescued for SSL renegotiation in <code>OpenSSL::SSL::SSLSocket</code>.
+ *  Blocking write (#write) can be emulated using #write_nonblock and
+ *  IO.select as follows: IO::WaitReadable should also be rescued for
+ *  SSL renegotiation in OpenSSL::SSL::SSLSocket.
  *
  *    while 0 < string.bytesize
  *      begin
@@ -9457,9 +9445,9 @@ rb_io_advise(int argc, VALUE *argv, VALUE io)
  *    end
  *
  *  === Parameters
- *  read_array:: an array of <code>IO</code> objects that wait until ready for read
- *  write_array:: an array of <code>IO</code> objects that wait until ready for write
- *  error_array:: an array of <code>IO</code> objects that wait for exceptions
+ *  read_array:: an array of IO objects that wait until ready for read
+ *  write_array:: an array of IO objects that wait until ready for write
+ *  error_array:: an array of IO objects that wait for exceptions
  *  timeout:: a numeric value in second
  *
  *  === Example
@@ -9910,9 +9898,9 @@ rb_fcntl(VALUE io, VALUE req, VALUE arg)
  *  query file-oriented I/O streams. Arguments and results are platform
  *  dependent. If <i>arg</i> is a number, its value is passed
  *  directly. If it is a string, it is interpreted as a binary sequence
- *  of bytes (<code>Array#pack</code> might be a useful way to build this
- *  string). On Unix platforms, see <code>fcntl(2)</code> for details.
- *  Not implemented on all platforms.
+ *  of bytes (Array#pack might be a useful way to build this string). On
+ *  Unix platforms, see <code>fcntl(2)</code> for details.  Not
+ *  implemented on all platforms.
  */
 
 static VALUE
@@ -10166,7 +10154,7 @@ pipe_pair_close(VALUE rw)
  *     IO.pipe(...) {|read_io, write_io| ... }
  *
  *  Creates a pair of pipe endpoints (connected to each other) and
- *  returns them as a two-element array of <code>IO</code> objects:
+ *  returns them as a two-element array of IO objects:
  *  <code>[</code> <i>read_io</i>, <i>write_io</i> <code>]</code>.
  *
  *  If a block is given, the block is called and
@@ -10463,8 +10451,8 @@ seek_before_access(VALUE argp)
  *     IO.read(name, [length [, offset]] [, opt] )   -> string
  *
  *  Opens the file, optionally seeks to the given +offset+, then returns
- *  +length+ bytes (defaulting to the rest of the file).  <code>read</code>
- *  ensures the file is closed before returning.
+ *  +length+ bytes (defaulting to the rest of the file).  #read ensures
+ *  the file is closed before returning.
  *
  *  If +name+ starts with a pipe character (<code>"|"</code>), a subprocess is
  *  created in the same way as Kernel#open, and its output is returned.
@@ -10529,10 +10517,10 @@ rb_io_s_read(int argc, VALUE *argv, VALUE io)
  *  call-seq:
  *     IO.binread(name, [length [, offset]] )   -> string
  *
- *  Opens the file, optionally seeks to the given <i>offset</i>, then returns
- *  <i>length</i> bytes (defaulting to the rest of the file).
- *  <code>binread</code> ensures the file is closed before returning.
- *  The open mode would be "rb:ASCII-8BIT".
+ *  Opens the file, optionally seeks to the given <i>offset</i>, then
+ *  returns <i>length</i> bytes (defaulting to the rest of the file).
+ *  #binread ensures the file is closed before returning.  The open mode
+ *  would be <code>"rb:ASCII-8BIT"</code>.
  *
  *     IO.binread("testfile")           #=> "This is line one\nThis is line two\nThis is line three\nAnd so on...\n"
  *     IO.binread("testfile", 20)       #=> "This is line one\nThi"
@@ -10635,10 +10623,9 @@ io_s_write(int argc, VALUE *argv, VALUE klass, int binary)
  *     IO.write(name, string [, offset] [, opt])   -> integer
  *
  *  Opens the file, optionally seeks to the given <i>offset</i>, writes
- *  <i>string</i>, then returns the length written.
- *  <code>write</code> ensures the file is closed before returning.
- *  If <i>offset</i> is not given in write mode, the file is truncated.
- *  Otherwise, it is not truncated.
+ *  <i>string</i>, then returns the length written.  #write ensures the
+ *  file is closed before returning.  If <i>offset</i> is not given in
+ *  write mode, the file is truncated.  Otherwise, it is not truncated.
  *
  *    IO.write("testfile", "0123456789", 20)  #=> 10
  *    # File could contain:  "This is line one\nThi0123456789two\nThis is line three\nAnd so on...\n"
@@ -10684,8 +10671,8 @@ rb_io_s_write(int argc, VALUE *argv, VALUE io)
  *     IO.binwrite(name, string, [offset] )             -> integer
  *     IO.binwrite(name, string, [offset], open_args )  -> integer
  *
- *  Same as <code>IO.write</code> except opening the file in binary mode
- *  and ASCII-8BIT encoding ("wb:ASCII-8BIT").
+ *  Same as IO.write except opening the file in binary mode and
+ *  ASCII-8BIT encoding (<code>"wb:ASCII-8BIT"</code>).
  */
 
 static VALUE
@@ -11578,9 +11565,8 @@ copy_stream_finalize(VALUE arg)
  *
  *  IO.copy_stream copies <i>src</i> to <i>dst</i>.
  *  <i>src</i> and <i>dst</i> is either a filename or an IO-like object.
- *  IO-like object for <i>src</i> should have <code>readpartial</code> or
- *  <code>read</code> method.
- *  IO-like object for <i>dst</i> should have <code>write</code> method.
+ *  IO-like object for <i>src</i> should have #readpartial or #read
+ *  method.  IO-like object for <i>dst</i> should have #write method.
  *  (Specialized mechanisms, such as sendfile system call, may be used
  *  on appropriate situation.)
  *
@@ -12103,11 +12089,11 @@ static VALUE argf_getpartial(int argc, VALUE *argv, VALUE argf, VALUE opts,
  *  The _outbuf_ will contain only the received data after the method call
  *  even if it is not empty at the beginning.
  *
- *  It raises <code>EOFError</code> on end of ARGF stream.
+ *  It raises EOFError on end of ARGF stream.
  *  Since ARGF stream is a concatenation of multiple files,
  *  internally EOF is occur for each file.
  *  ARGF.readpartial returns empty strings for EOFs except the last one and
- *  raises <code>EOFError</code> for the last one.
+ *  raises EOFError for the last one.
  *
  */
 
@@ -12417,7 +12403,7 @@ argf_each_line(int argc, VALUE *argv, VALUE argf)
 }
 
 /*
- *  This is a deprecated alias for <code>each_line</code>.
+ *  This is a deprecated alias for #each_line.
  */
 
 static VALUE
@@ -12464,7 +12450,7 @@ argf_each_byte(VALUE argf)
 }
 
 /*
- *  This is a deprecated alias for <code>each_byte</code>.
+ *  This is a deprecated alias for #each_byte.
  */
 
 static VALUE
@@ -12503,7 +12489,7 @@ argf_each_char(VALUE argf)
 }
 
 /*
- *  This is a deprecated alias for <code>each_char</code>.
+ *  This is a deprecated alias for #each_char.
  */
 
 static VALUE
@@ -12542,7 +12528,7 @@ argf_each_codepoint(VALUE argf)
 }
 
 /*
- *  This is a deprecated alias for <code>each_codepoint</code>.
+ *  This is a deprecated alias for #each_codepoint.
  */
 
 static VALUE