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.

Author: steveklabnik

src/libcore/io.rs

@@ -84,25 +84,29 @@ 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.
     */
     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.