io.c: improve docs
* io.c: [DOC] improve and harmonize docs for IO#read and ARGF#read;
fix invalid example code for IO#read to make it syntax highlighted.
* io.c: [DOC] various improvements for docs of IO, ARGF, and Kernel:
fix indent to ensure correct code block detection; sync "outbuf"
paragraph for {IO,ARGF}#read, {IO,ARGF}#readpartial, and IO#sysread;
fix formatting of call-seq's; improve Kernel#open example to use nil?;
fix RDoc markup and typos.
merge revision(s) 58008: [Backport #9294]
git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/branches/ruby_2_3@58169 b2dd03c8-39d4-4d8f-98ff-823fe69b080e