diff --git a/io.c b/io.c
index 58339d3..0275710 100644
--- a/io.c
+++ b/io.c
@@ -5526,8 +5526,12 @@ rb_io_initialize(int argc, VALUE *argv, VALUE io)
 
 /*
  *  call-seq:
- *     File.new(filename, mode="r")            => file
- *     File.new(filename [, mode [, perm]])    => file
+ *     File.new(filename, mode="r")                        => file
+ *     File.new(filename [, mode [, perm]])                => file
+ *     File.open(filename, mode="r")                       => file
+ *     File.open(filename, mode="r") {|f| block }          => obj
+ *     File.open(filename [, mode [, perm]])               => file
+ *     File.open(filename [, mode [, perm]]) {|f| block }  => obj
  *
 
  *  Opens the file named by _filename_ according to
@@ -5540,6 +5544,13 @@ rb_io_initialize(int argc, VALUE *argv, VALUE io)
  *  bits are platform dependent; on Unix systems, see
  *  <code>open(2)</code> for details.
  *
+ *  With no associated block, <code>open</code> is a synonym for
+ *  <code>File::new</code>. 
+ *  If the optional code block is given, it will
+ *  be passed <i>f</i> as an argument, and the File object will
+ *  automatically be closed when the block terminates. In this instance,
+ *  <code>File::open</code> returns the value of the block.
+ *
  *     f = File.new("testfile", "r")
  *     f = File.new("newfile",  "w+")
  *     f = File.new("newfile", File::CREAT|File::TRUNC|File::RDWR, 0644)