From 1065a92bf3bbe1f4bb11b7b7268a91529bbf8f89 Mon Sep 17 00:00:00 2001
From: Steve Klabnik <steve@steveklabnik.com>
Date: Sun, 19 May 2013 12:57:00 -0700
Subject: [PATCH 1/2] Elaborate a bit in the Reader docs regarding stream
 position.

Had a conversation with @cmr in IRC about some places that these
docs were confusing. The functions that advance the stream now say so.

In addition, I think that calling out the similarities to familliar C
functions should help people coming from other languages.
---
 src/libcore/io.rs | 16 +++++++++++++---
 1 file changed, 13 insertions(+), 3 deletions(-)

diff --git a/src/libcore/io.rs b/src/libcore/io.rs
index 77b486ca4461..8be02947ddb2 100644
--- a/src/libcore/io.rs
+++ b/src/libcore/io.rs
@@ -84,14 +84,16 @@ pub trait Reader {
 
     // FIXME (#2982): This should probably return an error.
     /**
-    * Reads bytes and puts them into `bytes`. Returns the number of
-    * bytes read.
+    * Reads bytes and puts them into `bytes`, advancing the cursor. Returns the
+    * number of bytes read.
     *
     * The number of bytes to be read is `len` or the end of the file,
     * whichever comes first.
     *
     * The buffer must be at least `len` bytes long.
     *
+    * `read` is conceptually similar to C's `fread`.
+    *
     * # Examples
     *
     * None right now.
@@ -99,10 +101,12 @@ pub trait Reader {
     fn read(&self, bytes: &mut [u8], len: uint) -> uint;
 
     /**
-    * Reads a single byte.
+    * Reads a single byte, advancing the cursor.
     *
     * In the case of an EOF or an error, returns a negative value.
     *
+    * `read_byte` is conceptually similar to C's `getc` function.
+    *
     * # Examples
     *
     * None right now.
@@ -112,6 +116,8 @@ pub trait Reader {
     /**
     * Returns a boolean value: are we currently at EOF?
     *
+    * `eof` is conceptually similar to C's `feof` function.
+    *
     * # Examples
     *
     * None right now.
@@ -124,6 +130,8 @@ pub trait Reader {
     * Takes an optional SeekStyle, which affects how we seek from the
     * position. See `SeekStyle` docs for more details.
     *
+    * `seek` is conceptually similar to C's `fseek`.
+    *
     * # Examples
     *
     * None right now.
@@ -133,6 +141,8 @@ pub trait Reader {
     /**
     * Returns the current position within the stream.
     *
+    * `tell` is conceptually similar to C's `ftell` function.
+    *
     * # Examples
     *
     * None right now.

From dcc2879266ee6e733a4729b425da0ff25aeebd1f Mon Sep 17 00:00:00 2001
From: Steve Klabnik <steve@steveklabnik.com>
Date: Sun, 19 May 2013 22:40:13 -0600
Subject: [PATCH 2/2] Add a few 'function's.

This is now 100% consistent. Whoops!
---
 src/libcore/io.rs | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/libcore/io.rs b/src/libcore/io.rs
index 8be02947ddb2..ad4ced47ae54 100644
--- a/src/libcore/io.rs
+++ b/src/libcore/io.rs
@@ -92,7 +92,7 @@ pub trait Reader {
     *
     * The buffer must be at least `len` bytes long.
     *
-    * `read` is conceptually similar to C's `fread`.
+    * `read` is conceptually similar to C's `fread` function.
     *
     * # Examples
     *
@@ -130,7 +130,7 @@ pub trait Reader {
     * Takes an optional SeekStyle, which affects how we seek from the
     * position. See `SeekStyle` docs for more details.
     *
-    * `seek` is conceptually similar to C's `fseek`.
+    * `seek` is conceptually similar to C's `fseek` function.
     *
     * # Examples
     *