object.c: [DOC] Revise documentation

* object.c: [DOC] Revise documentation by Marcus Stollsteimer at
  [ruby-core:66368].  [Bug #10526]
  * #inspect: be more specific about generated string, remove
    obsolete example.
  * #nil?: use code examples instead of different call-seq's.
  * #tap: clarify what is yielded.
  * Integer(): be more specific about to_int and to_i, remove
    reference to Ruby 1.8.
  * Array(): fix error.
  * Class: fix variable name style and indentation in example.
  * improve consistency, fix typos and formatting.

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