[ ruby-Bugs-5293 ] "ri File.open" is misleading

Bugs item #5293, was opened at 2006-08-03 11:38
You can respond by visiting: 
http://rubyforge.org/tracker/?func=detail&atid=1698&aid=5293&group_id=426

Category: Core
Group: 1.9.x
Status: Open
Resolution: None
Priority: 3
Submitted By: Elliott Hughes (enh)
Assigned to: Nobody (None)
Summary: "ri File.open" is misleading

Initial Comment:
i know i want File.open rather than File.new, because i want to pass a block. but i can't remember the details, so i ask for help:

$ ri1.9 File.open
Nothing known about File.open

okay, i know that File extends IO, so how about IO.open?

$ ri1.9 IO.open
--------------------------------------------------------------- IO::open
     IO.open(fd, mode_string="r" )               => io
     IO.open(fd, mode_string="r" ) {|io| block } => obj
------------------------------------------------------------------------
     With no associated block, +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.

well, that's not wrong, but it is misleading. the on-line pickaxe is much better:

  open     	 File.open( fileName, aModeString="r" ) -> file
                 File.open( fileName [, aModeNum [ aPermNum ] ] ) -> file
                 File.open( fileName, aModeString="r" ) {| file | block } -> nil
                 File.open( fileName [, aModeNum [ aPermNum ] ] ) {| file | block } -> nil
	
  With no associated block, open is a synonym for File.new . If the
  optional code block is given, it will be passed file as an argument,
  and the file will automatically be closed when the block terminates.
  In this instance, File.open returns nil.

i wonder how many other inherited methods have their documentation made (a) hard to access and (b) hard to understand in this way?

 --elliott


----------------------------------------------------------------------

You can respond by visiting: 
http://rubyforge.org/tracker/?func=detail&atid=1698&aid=5293&group_id=426