fix up documentation for fd vs IO objects

We support both, but IO objects are easier to use so
refer to those in the documentation.

1 files changed, 46 insertions, 47 deletions

diff --git a/ext/io_splice/io_splice_ext.c b/ext/io_splice/io_splice_ext.c
index 80c8cde..ffccef1 100644
--- a/ext/io_splice/io_splice_ext.c
+++ b/ext/io_splice/io_splice_ext.c
@@ -137,14 +137,14 @@ static VALUE nogvl_splice(void *ptr)
 static ssize_t do_splice(int argc, VALUE *argv, unsigned dflags)
 {
         off_t i = 0, o = 0;
-        VALUE fd_in, off_in, fd_out, off_out, len, flags;
+        VALUE io_in, off_in, io_out, off_out, len, flags;
         struct splice_args a;
         ssize_t bytes;
         ssize_t total = 0;
         unsigned waitall;
 
         rb_scan_args(argc, argv, "51",
-                     &fd_in, &off_in, &fd_out, &off_out, &len, &flags);
+                     &io_in, &off_in, &io_out, &off_out, &len, &flags);
 
         a.off_in = NIL_P(off_in) ? NULL : (i = NUM2OFFT(off_in), &i);
         a.off_out = NIL_P(off_out) ? NULL : (o = NUM2OFFT(off_out), &o);
@@ -155,16 +155,16 @@ static ssize_t do_splice(int argc, VALUE *argv, unsigned dflags)
                 a.flags ^= WAITALL;
 
         for (;;) {
-                a.fd_in = check_fileno(fd_in);
-                a.fd_out = check_fileno(fd_out);
+                a.fd_in = check_fileno(io_in);
+                a.fd_out = check_fileno(io_out);
                 bytes = (ssize_t)io_run(nogvl_splice, &a);
                 if (bytes == -1) {
                         if (errno == EINTR)
                                 continue;
                         if (waitall && errno == EAGAIN) {
-                                rb_io_wait_readable(check_fileno(fd_in));
+                                rb_io_wait_readable(check_fileno(io_in));
                                 errno = EAGAIN;
-                                rb_io_wait_writable(check_fileno(fd_out));
+                                rb_io_wait_writable(check_fileno(io_out));
                                 continue;
                         }
                         if (total > 0)
@@ -188,11 +188,11 @@ static ssize_t do_splice(int argc, VALUE *argv, unsigned dflags)
 
 /*
  * call-seq:
- *    IO.splice(fd_in, off_in, fd_out, off_out, len) => integer
- *    IO.splice(fd_in, off_in, fd_out, off_out, len, flags) => integer
+ *    IO.splice(io_in, off_in, io_out, off_out, len) => integer
+ *    IO.splice(io_in, off_in, io_out, off_out, len, flags) => integer
  *
- * Splice +len+ bytes from/to a pipe.  Either +fd_in+ or +fd_out+
- * MUST be a pipe.  +fd_in+ and +fd_out+ may BOTH be pipes as of
+ * Splice +len+ bytes from/to a pipe.  Either +io_in+ or +io_out+
+ * MUST be a pipe.  +io_in+ and +io_out+ may BOTH be pipes as of
  * Linux 2.6.31 or later.
  *
  * +off_in+ and +off_out+ if non-nil may be used to
@@ -201,22 +201,18 @@ static ssize_t do_splice(int argc, VALUE *argv, unsigned dflags)
  * +flags+ defaults to zero if unspecified.
  * +flags+ may be a bitmask of the following flags:
  *
- * IO::Splice::F_MOVE, IO::Splice::F_NONBLOCK, IO::Splice::F_MORE
+ * * IO::Splice::F_MOVE
+ * * IO::Splice::F_NONBLOCK
+ * * IO::Splice::F_MORE
+ * * IO::Splice::WAITALL
  *
  * Returns the number of bytes spliced.
- * Raises EOFError when +fd_in+ has reached end of file.
+ * Raises EOFError when +io_in+ has reached end of file.
  * Raises Errno::EAGAIN if the IO::Splice::F_NONBLOCK flag is set
  * and the pipe has no data to read from or space to write to.  May
  * also raise Errno::EAGAIN if the non-pipe descriptor has no data
  * to read from or space to write to.
  *
- *     rd, wr = (pipe = IO.pipe).map { |io| io.fileno }
- *     src_io, dst_io = File.open("/path/to/src"), File.open("/path/to/dst")
- *     src, dst = src_io.fileno, dst_io.fileno
- *
- *     nr = IO.splice(src, nil, wr, nil, IO::Splice::PIPE_CAPA, 0)
- *     IO.splice(rd, nil, dst, nil, nr, 0)
- *
  * As splice never exposes buffers to userspace, it will not take
  * into account userspace buffering done by Ruby or stdio.  It is
  * also not subject to encoding/decoding filters under Ruby 1.9.
@@ -241,8 +237,8 @@ static VALUE my_splice(int argc, VALUE *argv, VALUE self)
 
 /*
  * call-seq:
- *    IO.trysplice(fd_in, off_in, fd_out, off_out, len) => integer
- *    IO.trysplice(fd_in, off_in, fd_out, off_out, len, flags) => integer
+ *    IO.trysplice(io_in, off_in, io_out, off_out, len) => integer
+ *    IO.trysplice(io_in, off_in, io_out, off_out, len, flags) => integer
  *
  * Exactly like IO.splice, except +:EAGAIN+ is returned when either
  * the read or write end would block instead of raising Errno::EAGAIN.
@@ -283,13 +279,13 @@ static VALUE nogvl_tee(void *ptr)
 
 static ssize_t do_tee(int argc, VALUE *argv, unsigned dflags)
 {
-        VALUE fd_in, fd_out, len, flags;
+        VALUE io_in, io_out, len, flags;
         struct tee_args a;
         ssize_t bytes;
         ssize_t total = 0;
         unsigned waitall;
 
-        rb_scan_args(argc, argv, "31", &fd_in, &fd_out, &len, &flags);
+        rb_scan_args(argc, argv, "31", &io_in, &io_out, &len, &flags);
         a.len = (size_t)NUM2SIZET(len);
         a.flags = NIL_P(flags) ? dflags : NUM2UINT(flags) | dflags;
         waitall = a.flags & WAITALL;
@@ -297,16 +293,16 @@ static ssize_t do_tee(int argc, VALUE *argv, unsigned dflags)
                 a.flags ^= WAITALL;
 
         for (;;) {
-                a.fd_in = check_fileno(fd_in);
-                a.fd_out = check_fileno(fd_out);
+                a.fd_in = check_fileno(io_in);
+                a.fd_out = check_fileno(io_out);
                 bytes = (ssize_t)io_run(nogvl_tee, &a);
                 if (bytes == -1) {
                         if (errno == EINTR)
                                 continue;
                         if (waitall && errno == EAGAIN) {
-                                rb_io_wait_readable(check_fileno(fd_in));
+                                rb_io_wait_readable(check_fileno(io_in));
                                 errno = EAGAIN;
-                                rb_io_wait_writable(check_fileno(fd_out));
+                                rb_io_wait_writable(check_fileno(io_out));
                                 continue;
                         }
                         if (total > 0)
@@ -328,19 +324,22 @@ static ssize_t do_tee(int argc, VALUE *argv, unsigned dflags)
 
 /*
  * call-seq:
- *   IO.tee(fd_in, fd_out, len) => integer
- *   IO.tee(fd_in, fd_out, len, flags) => integer
+ *   IO.tee(io_in, io_out, len) => integer
+ *   IO.tee(io_in, io_out, len, flags) => integer
  *
- * Copies up to +len+ bytes of data from +fd_in+ to +fd_out+.  +fd_in+
- * and +fd_out+ must both refer to pipe descriptors.  +fd_in+ and +fd_out+
+ * Copies up to +len+ bytes of data from +io_in+ to +io_out+.  +io_in+
+ * and +io_out+ must both refer to pipe descriptors.  +io_in+ and +io_out+
  * may not be endpoints of the same pipe.
  *
- * +flags+ may be zero (the default) or IO::Splice::F_NONBLOCK
+ * +flags+ may be zero (the default) or a combination of:
+ * * IO::Splice::F_NONBLOCK
+ * * IO::Splice::WAITALL
+ *
  * Other IO::Splice flags are currently unimplemented or have no effect.
  *
  * Returns the number of bytes duplicated if successful.
- * Raises EOFError when +fd_in+ is closed and emptied.
- * Raises Errno::EAGAIN when +fd_in+ is empty and/or +fd_out+ is full
+ * Raises EOFError when +io_in+ is closed and emptied.
+ * Raises Errno::EAGAIN when +io_in+ is empty and/or +io_out+ is full
  * and +flags+ contains IO::Splice::F_NONBLOCK
  *
  * Consider using IO.trytee if you are using IO::Splice::F_NONBLOCK
@@ -363,8 +362,8 @@ static VALUE my_tee(int argc, VALUE *argv, VALUE self)
 
 /*
  * call-seq:
- *    IO.trytee(fd_in, fd_out, len) => integer
- *    IO.trytee(fd_in, fd_out, len, flags) => integer
+ *    IO.trytee(io_in, io_out, len) => integer
+ *    IO.trytee(io_in, io_out, len, flags) => integer
  *
  * Exactly like IO.tee, except +:EAGAIN+ is returned when either
  * the read or write end would block instead of raising Errno::EAGAIN.
@@ -456,13 +455,13 @@ static void advance_vmsplice_args(struct vmsplice_args *a, long n)
 
 /*
  * call-seq:
- *   IO.vmsplice(fd, string_array) => integer
- *   IO.vmsplice(fd, string_array, flags) => integer
- *   IO.vmsplice(fd, string) => integer
- *   IO.vmsplice(fd, string, flags) => integer
+ *   IO.vmsplice(io, string_array) => integer
+ *   IO.vmsplice(io, string_array, flags) => integer
+ *   IO.vmsplice(io, string) => integer
+ *   IO.vmsplice(io, string, flags) => integer
  *
- * Transfers an array of strings into the pipe descriptor given by fd.
- * +fd+ must be the writable end of a pipe.
+ * Transfers an array of strings into the pipe descriptor given by io.
+ * +io+ must be the writable end of a pipe.
  *
  * This may allow the kernel to avoid data copies in some cases.
  * but is (probably) of limited usefulness in Ruby.  If you have
@@ -482,9 +481,9 @@ static VALUE my_vmsplice(int argc, VALUE * argv, VALUE self)
         ssize_t rv = 0;
         ssize_t left;
         struct vmsplice_args a;
-        VALUE fd, data, flags;
+        VALUE io, data, flags;
 
-        rb_scan_args(argc, argv, "21", &fd, &data, &flags);
+        rb_scan_args(argc, argv, "21", &io, &data, &flags);
 
         switch (TYPE(data)) {
         case T_STRING: {
@@ -504,7 +503,7 @@ static VALUE my_vmsplice(int argc, VALUE * argv, VALUE self)
                          "(expected a String or Array of strings)",
                          rb_obj_classname(data));
         }
-        a.fd = my_fileno(fd);
+        a.fd = my_fileno(io);
         a.flags = NIL_P(flags) ? 0 : NUM2UINT(flags);
 
         for (;;) {
@@ -515,7 +514,7 @@ static VALUE my_vmsplice(int argc, VALUE * argv, VALUE self)
                                 if (a.flags & SPLICE_F_NONBLOCK) {
                                         rb_sys_fail("vmsplice");
                                 } else {
-                                        a.fd = check_fileno(fd);
+                                        a.fd = check_fileno(io);
                                         if (rb_io_wait_writable(a.fd))
                                                 continue;
                                 }
@@ -529,7 +528,7 @@ static VALUE my_vmsplice(int argc, VALUE * argv, VALUE self)
                         if (rv > 0)
                                 break;
                         if (errno == EINTR) {
-                                a.fd = check_fileno(fd);
+                                a.fd = check_fileno(io);
                                 continue;
                         }
                         rb_sys_fail("vmsplice");