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.

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