Bugs: Browse | Submit New | Admin

[#5293] "ri File.open" is misleading

Date:
2006-08-03 18:38
Priority:
3
Submitted By:
Elliott Hughes (enh)
Assigned To:
Eric Hodel (drbrain)
Category:
Documentation, ri, and rdoc
State:
Open
Platform:
 
Summary:
"ri File.open" is misleading

Detailed description
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

Add A Comment: Notepad

Please login


Followup

No Followups Have Been Posted

Attached Files:

Name Description Download
No Files Currently Attached

Changes:

Field Old Value Date By
category_idMisc / Other Standard Library2007-05-29 16:25zenspider
summary"ri File.open" is misleading2007-05-29 16:25zenspider
category_idLanguage / Runtime / Core Libraries2007-05-29 15:54zenspider
summary"ri File.open" is misleading2007-05-29 15:54zenspider
assigned_tozenspider2007-03-20 00:31zenspider
summary"ri File.open" is misleading2006-11-02 07:21zenspider
assigned_tonone2006-11-02 07:21zenspider