diff --git a/io.c b/io.c
index 5d72af16bc..c0bc351a01 100644
--- a/io.c
+++ b/io.c
@@ -2072,6 +2072,9 @@ rb_io_close(VALUE io)
  *  an <code>IOError</code> is raised if such an attempt is made. I/O
  *  streams are automatically closed when they are claimed by the
  *  garbage collector.
+ *
+ *  If <em>ios</em> is opened by <code>IO.popen</code>,
+ *  <code>close</code> sets <code>$?</code>.
  */
 
 static VALUE
@@ -2976,7 +2979,9 @@ pipe_open(int argc, VALUE *argv, const char *mode)
  *
  *  If a block is given, Ruby will run the command as a child connected
  *  to Ruby with a pipe. Ruby's end of the pipe will be passed as a
- *  parameter to the block. In this case <code>IO::popen</code> returns
+ *  parameter to the block.
+ *  At the end of block, Ruby close the pipe and sets <code>$?</code>.
+ *  In this case <code>IO::popen</code> returns
  *  the value of the block.
  *
  *  If a block is given with a _cmd_ of ``<code>-</code>'',
@@ -2992,6 +2997,7 @@ pipe_open(int argc, VALUE *argv, const char *mode)
  *     puts "Parent is #{Process.pid}"
  *     IO.popen("date") { |f| puts f.gets }
  *     IO.popen("-") {|f| $stderr.puts "#{Process.pid} is here, f is #{f}"}
+ *     p $?
  *     IO.popen(%w"sed -e s|^|<foo>| -e s&$&;zot;&", "r+") {|f|
  *       f.puts "bar"; f.close_write; puts f.gets
  *     }
@@ -3003,6 +3009,7 @@ pipe_open(int argc, VALUE *argv, const char *mode)
  *     Wed Apr  9 08:53:52 CDT 2003
  *     26169 is here, f is
  *     26166 is here, f is #<IO:0x401b3d44>
+ *     #<Process::Status: pid=26166,exited(0)>
  *     <foo>bar;zot;
  */