From 1d658d9b97434a391a7e202a033080555a2bc69e Mon Sep 17 00:00:00 2001
From: Steve Klabnik <steve@steveklabnik.com>
Date: Mon, 1 Apr 2013 18:03:54 -0700
Subject: [PATCH 1/3] Improve docs for Core::ReaderUtil.

I filled out better descriptions for all of the neccesary
functions.
---
 src/libcore/io.rs | 375 +++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 335 insertions(+), 40 deletions(-)

diff --git a/src/libcore/io.rs b/src/libcore/io.rs
index 60a0ee4fa9713..1a15a9f5d809c 100644
--- a/src/libcore/io.rs
+++ b/src/libcore/io.rs
@@ -93,120 +93,415 @@ impl Reader for @Reader {
     }
 }
 
-/// Generic utility functions defined on readers.
+/**
+* The `ReaderUtil` trait is a home for many of the utility functions
+* a particular Reader should implement.
+* 
+* The default `Reader` trait is focused entirely on bytes. `ReaderUtil` is based
+* on higher-level concepts like 'chars' and 'lines.'
+* 
+* # Examples:
+*
+* None right now.
+*/
 pub trait ReaderUtil {
 
-    /// Read len bytes into a new vec.
+    /**
+    * Reads `len` number of bytes, and gives you a new vector back.
+    *
+    * # Examples
+    *
+    * None right now.
+    */
     fn read_bytes(&self, len: uint) -> ~[u8];
 
-    /// Read up until a specified character (which is optionally included) or EOF.
+    /**
+    * Reads up until a specific character or EOF.
+    * 
+    * The `include` parameter specifies if the character should be included
+    * in the returned string.
+    *
+    * # Examples
+    *
+    * None right now.
+    */
     fn read_until(&self, c: char, include: bool) -> ~str;
 
-    /// Read up until the first '\n' char (which is not returned), or EOF.
+    /**
+    * Reads up until the first '\n' or EOF.
+    * 
+    * The '\n' is not included in the result.
+    *
+    * # Examples
+    *
+    * None right now.
+    */
     fn read_line(&self) -> ~str;
 
-    /// Read n utf-8 encoded chars.
+    /**
+    * Reads `n` chars.
+    * 
+    * Assumes that those chars are UTF-8 encoded.
+    * 
+    * The '\n' is not included in the result.
+    *
+    * # Examples
+    *
+    * None right now.
+    */
     fn read_chars(&self, n: uint) -> ~[char];
 
-    /// Read a single utf-8 encoded char.
+    /**
+    * Reads a single UTF-8 encoded char.
+    *
+    * # Examples
+    *
+    * None right now.
+    */
     fn read_char(&self) -> char;
 
-    /// Read up until the first null byte (which is not returned), or EOF.
+    /**
+    * Reads up until the first null byte or EOF.
+    *
+    * The null byte is not returned.
+    *
+    * # Examples
+    *
+    * None right now.
+    */
     fn read_c_str(&self) -> ~str;
 
-    /// Read all the data remaining in the stream in one go.
+    /**
+    * Reads all remaining data in the stream.
+    *
+    * # Examples
+    *
+    * None right now.
+    */
     fn read_whole_stream(&self) -> ~[u8];
 
-    /// Iterate over every byte until the iterator breaks or EOF.
+    /**
+    * Iterate over every byte until EOF or the iterator breaks.
+    *
+    * # Examples
+    *
+    * None right now.
+    */
     fn each_byte(&self, it: &fn(int) -> bool);
 
-    /// Iterate over every char until the iterator breaks or EOF.
+    /**
+    * Iterate over every char until EOF or the iterator breaks.
+    *
+    * # Examples
+    *
+    * None right now.
+    */
     fn each_char(&self, it: &fn(char) -> bool);
 
-    /// Iterate over every line until the iterator breaks or EOF.
+    /**
+    * Iterate over every line until EOF or the iterator breaks.
+    *
+    * # Examples
+    *
+    * None right now.
+    */
     fn each_line(&self, it: &fn(&str) -> bool);
 
-    /// Read all the lines of the file into a vector.
+    /**
+    * Reads all of the lines in the stream.
+    * 
+    * Returns a vector of those lines.
+    *
+    * # Examples
+    *
+    * None right now.
+    */
     fn read_lines(&self) -> ~[~str];
 
-    /// Read n (between 1 and 8) little-endian unsigned integer bytes.
+    /**
+    * Reads `n` little-endian unsigned integer bytes.
+    * 
+    * `n` must be between 1 and 8, inclusive.
+    * 
+    * # Examples
+    *
+    * None right now.
+    */
     fn read_le_uint_n(&self, nbytes: uint) -> u64;
 
-    /// Read n (between 1 and 8) little-endian signed integer bytes.
+    /**
+    * Reads `n` little-endian signed integer bytes.
+    * 
+    * `n` must be between 1 and 8, inclusive.
+    * 
+    * # Examples
+    *
+    * None right now.
+    */
     fn read_le_int_n(&self, nbytes: uint) -> i64;
 
-    /// Read n (between 1 and 8) big-endian unsigned integer bytes.
+    /**
+    * Reads `n` big-endian unsigned integer bytes.
+    * 
+    * `n` must be between 1 and 8, inclusive.
+    * 
+    * # Examples
+    *
+    * None right now.
+    */
     fn read_be_uint_n(&self, nbytes: uint) -> u64;
 
-    /// Read n (between 1 and 8) big-endian signed integer bytes.
+    /**
+    * Reads `n` big-endian signed integer bytes.
+    * 
+    * `n` must be between 1 and 8, inclusive.
+    * 
+    * # Examples
+    *
+    * None right now.
+    */
     fn read_be_int_n(&self, nbytes: uint) -> i64;
 
-    /// Read a little-endian uint (number of bytes depends on system).
+    /**
+    * Reads a little-endian unsigned integer.
+    * 
+    * The number of bytes returned is system-dependant.
+    * 
+    * # Examples
+    *
+    * None right now.
+    */
     fn read_le_uint(&self) -> uint;
 
-    /// Read a little-endian int (number of bytes depends on system).
+    /**
+    * Reads a little-endian integer.
+    * 
+    * The number of bytes returned is system-dependant.
+    * 
+    * # Examples
+    *
+    * None right now.
+    */
     fn read_le_int(&self) -> int;
 
-    /// Read a big-endian uint (number of bytes depends on system).
+    /**
+    * Reads a big-endian unsigned integer.
+    * 
+    * The number of bytes returned is system-dependant.
+    * 
+    * # Examples
+    *
+    * None right now.
+    */
     fn read_be_uint(&self) -> uint;
 
-    /// Read a big-endian int (number of bytes depends on system).
+    /**
+    * Reads a big-endian integer.
+    * 
+    * The number of bytes returned is system-dependant.
+    * 
+    * # Examples
+    *
+    * None right now.
+    */
     fn read_be_int(&self) -> int;
 
-    /// Read a big-endian u64 (8 bytes).
+    /**
+    * Reads a big-endian `u64`.
+    * 
+    * `u64`s are 8 bytes long.
+    * 
+    * # Examples
+    *
+    * None right now.
+    */
     fn read_be_u64(&self) -> u64;
 
-    /// Read a big-endian u32 (4 bytes).
+    /**
+    * Reads a big-endian `u32`.
+    * 
+    * `u32`s are 4 bytes long.
+    * 
+    * # Examples
+    *
+    * None right now.
+    */
     fn read_be_u32(&self) -> u32;
 
-    /// Read a big-endian u16 (2 bytes).
+    /**
+    * Reads a big-endian `u16`.
+    * 
+    * `u16`s are 2 bytes long.
+    * 
+    * # Examples
+    *
+    * None right now.
+    */
     fn read_be_u16(&self) -> u16;
 
-    /// Read a big-endian i64 (8 bytes).
+    /**
+    * Reads a big-endian `i64`.
+    * 
+    * `i64`s are 8 bytes long.
+    * 
+    * # Examples
+    *
+    * None right now.
+    */
     fn read_be_i64(&self) -> i64;
 
-    /// Read a big-endian i32 (4 bytes).
+    /**
+    * Reads a big-endian `i32`.
+    * 
+    * `i32`s are 4 bytes long.
+    * 
+    * # Examples
+    *
+    * None right now.
+    */
     fn read_be_i32(&self) -> i32;
 
-    /// Read a big-endian i16 (2 bytes).
+    /**
+    * Reads a big-endian `i16`.
+    * 
+    * `i16`s are 2 bytes long.
+    * 
+    * # Examples
+    *
+    * None right now.
+    */
     fn read_be_i16(&self) -> i16;
 
-    /// Read a big-endian IEEE754 double-precision floating-point (8 bytes).
+    /**
+    * Reads a big-endian `f64`.
+    * 
+    * `f64`s are 8 byte, IEEE754 double-precision floating point numbers.
+    * 
+    * # Examples
+    *
+    * None right now.
+    */
     fn read_be_f64(&self) -> f64;
 
-    /// Read a big-endian IEEE754 single-precision floating-point (4 bytes).
+    /**
+    * Reads a big-endian `f32`.
+    * 
+    * `f32`s are 4 byte, IEEE754 single-precision floating point numbers.
+    * 
+    * # Examples
+    *
+    * None right now.
+    */
     fn read_be_f32(&self) -> f32;
 
-    /// Read a little-endian u64 (8 bytes).
+    /**
+    * Reads a little-endian `u64`.
+    * 
+    * `u64`s are 8 bytes long.
+    * 
+    * # Examples
+    *
+    * None right now.
+    */
     fn read_le_u64(&self) -> u64;
 
-    /// Read a little-endian u32 (4 bytes).
+    /**
+    * Reads a little-endian `u32`.
+    * 
+    * `u32`s are 4 bytes long.
+    * 
+    * # Examples
+    *
+    * None right now.
+    */
     fn read_le_u32(&self) -> u32;
 
-    /// Read a little-endian u16 (2 bytes).
+    /**
+    * Reads a little-endian `u16`.
+    * 
+    * `u16`s are 2 bytes long.
+    * 
+    * # Examples
+    *
+    * None right now.
+    */
     fn read_le_u16(&self) -> u16;
 
-    /// Read a litle-endian i64 (8 bytes).
+    /**
+    * Reads a little-endian `i64`.
+    * 
+    * `i64`s are 8 bytes long.
+    * 
+    * # Examples
+    *
+    * None right now.
+    */
     fn read_le_i64(&self) -> i64;
 
-    /// Read a litle-endian i32 (4 bytes).
+    /**
+    * Reads a little-endian `i32`.
+    * 
+    * `i32`s are 4 bytes long.
+    * 
+    * # Examples
+    *
+    * None right now.
+    */
     fn read_le_i32(&self) -> i32;
 
-    /// Read a litle-endian i16 (2 bytes).
+    /**
+    * Reads a little-endian `i16`.
+    * 
+    * `i16`s are 2 bytes long.
+    * 
+    * # Examples
+    *
+    * None right now.
+    */
     fn read_le_i16(&self) -> i16;
 
-    /// Read a litten-endian IEEE754 double-precision floating-point
-    /// (8 bytes).
+    /**
+    * Reads a little-endian `f64`.
+    * 
+    * `f64`s are 8 byte, IEEE754 double-precision floating point numbers.
+    * 
+    * # Examples
+    *
+    * None right now.
+    */
     fn read_le_f64(&self) -> f64;
 
-    /// Read a litten-endian IEEE754 single-precision floating-point
-    /// (4 bytes).
+    /**
+    * Reads a little-endian `f32`.
+    * 
+    * `f32`s are 4 byte, IEEE754 single-precision floating point numbers.
+    * 
+    * # Examples
+    *
+    * None right now.
+    */
     fn read_le_f32(&self) -> f32;
 
-    /// Read a u8 (1 byte).
+    /**
+    * Read a u8. 
+    * 
+    * `u8`s are 1 byte.
+    * 
+    * # Examples
+    *
+    * None right now.
+    */
     fn read_u8(&self) -> u8;
 
-    /// Read a i8 (1 byte).
+    /**
+    * Read an i8. 
+    * 
+    * `u8`s are 1 byte.
+    * 
+    * # Examples
+    *
+    * None right now.
+    */
     fn read_i8(&self) -> i8;
 }
 

From 948ff6056f9f4c2fe312da98456d3d6b7d1ce699 Mon Sep 17 00:00:00 2001
From: Steve Klabnik <steve@steveklabnik.com>
Date: Mon, 1 Apr 2013 18:20:30 -0700
Subject: [PATCH 2/3] Typo fix. u8 -> i8

---
 src/libcore/io.rs | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/libcore/io.rs b/src/libcore/io.rs
index 1a15a9f5d809c..b3dfe8d46af2c 100644
--- a/src/libcore/io.rs
+++ b/src/libcore/io.rs
@@ -496,7 +496,7 @@ pub trait ReaderUtil {
     /**
     * Read an i8. 
     * 
-    * `u8`s are 1 byte.
+    * `i8`s are 1 byte.
     * 
     * # Examples
     *

From a3e2d6ea81b93bf41b4387be935b5f488e47ef73 Mon Sep 17 00:00:00 2001
From: Steve Klabnik <steve@steveklabnik.com>
Date: Tue, 2 Apr 2013 17:31:42 -0700
Subject: [PATCH 3/3] Remove excess trailing whitespace.

---
 src/libcore/io.rs | 122 +++++++++++++++++++++++-----------------------
 1 file changed, 61 insertions(+), 61 deletions(-)

diff --git a/src/libcore/io.rs b/src/libcore/io.rs
index b3dfe8d46af2c..c49117fe23d48 100644
--- a/src/libcore/io.rs
+++ b/src/libcore/io.rs
@@ -96,10 +96,10 @@ impl Reader for @Reader {
 /**
 * The `ReaderUtil` trait is a home for many of the utility functions
 * a particular Reader should implement.
-* 
+*
 * The default `Reader` trait is focused entirely on bytes. `ReaderUtil` is based
 * on higher-level concepts like 'chars' and 'lines.'
-* 
+*
 * # Examples:
 *
 * None right now.
@@ -117,7 +117,7 @@ pub trait ReaderUtil {
 
     /**
     * Reads up until a specific character or EOF.
-    * 
+    *
     * The `include` parameter specifies if the character should be included
     * in the returned string.
     *
@@ -129,7 +129,7 @@ pub trait ReaderUtil {
 
     /**
     * Reads up until the first '\n' or EOF.
-    * 
+    *
     * The '\n' is not included in the result.
     *
     * # Examples
@@ -140,9 +140,9 @@ pub trait ReaderUtil {
 
     /**
     * Reads `n` chars.
-    * 
+    *
     * Assumes that those chars are UTF-8 encoded.
-    * 
+    *
     * The '\n' is not included in the result.
     *
     * # Examples
@@ -209,7 +209,7 @@ pub trait ReaderUtil {
 
     /**
     * Reads all of the lines in the stream.
-    * 
+    *
     * Returns a vector of those lines.
     *
     * # Examples
@@ -220,9 +220,9 @@ pub trait ReaderUtil {
 
     /**
     * Reads `n` little-endian unsigned integer bytes.
-    * 
+    *
     * `n` must be between 1 and 8, inclusive.
-    * 
+    *
     * # Examples
     *
     * None right now.
@@ -231,9 +231,9 @@ pub trait ReaderUtil {
 
     /**
     * Reads `n` little-endian signed integer bytes.
-    * 
+    *
     * `n` must be between 1 and 8, inclusive.
-    * 
+    *
     * # Examples
     *
     * None right now.
@@ -242,9 +242,9 @@ pub trait ReaderUtil {
 
     /**
     * Reads `n` big-endian unsigned integer bytes.
-    * 
+    *
     * `n` must be between 1 and 8, inclusive.
-    * 
+    *
     * # Examples
     *
     * None right now.
@@ -253,9 +253,9 @@ pub trait ReaderUtil {
 
     /**
     * Reads `n` big-endian signed integer bytes.
-    * 
+    *
     * `n` must be between 1 and 8, inclusive.
-    * 
+    *
     * # Examples
     *
     * None right now.
@@ -264,9 +264,9 @@ pub trait ReaderUtil {
 
     /**
     * Reads a little-endian unsigned integer.
-    * 
+    *
     * The number of bytes returned is system-dependant.
-    * 
+    *
     * # Examples
     *
     * None right now.
@@ -275,9 +275,9 @@ pub trait ReaderUtil {
 
     /**
     * Reads a little-endian integer.
-    * 
+    *
     * The number of bytes returned is system-dependant.
-    * 
+    *
     * # Examples
     *
     * None right now.
@@ -286,9 +286,9 @@ pub trait ReaderUtil {
 
     /**
     * Reads a big-endian unsigned integer.
-    * 
+    *
     * The number of bytes returned is system-dependant.
-    * 
+    *
     * # Examples
     *
     * None right now.
@@ -297,9 +297,9 @@ pub trait ReaderUtil {
 
     /**
     * Reads a big-endian integer.
-    * 
+    *
     * The number of bytes returned is system-dependant.
-    * 
+    *
     * # Examples
     *
     * None right now.
@@ -308,9 +308,9 @@ pub trait ReaderUtil {
 
     /**
     * Reads a big-endian `u64`.
-    * 
+    *
     * `u64`s are 8 bytes long.
-    * 
+    *
     * # Examples
     *
     * None right now.
@@ -319,9 +319,9 @@ pub trait ReaderUtil {
 
     /**
     * Reads a big-endian `u32`.
-    * 
+    *
     * `u32`s are 4 bytes long.
-    * 
+    *
     * # Examples
     *
     * None right now.
@@ -330,9 +330,9 @@ pub trait ReaderUtil {
 
     /**
     * Reads a big-endian `u16`.
-    * 
+    *
     * `u16`s are 2 bytes long.
-    * 
+    *
     * # Examples
     *
     * None right now.
@@ -341,9 +341,9 @@ pub trait ReaderUtil {
 
     /**
     * Reads a big-endian `i64`.
-    * 
+    *
     * `i64`s are 8 bytes long.
-    * 
+    *
     * # Examples
     *
     * None right now.
@@ -352,9 +352,9 @@ pub trait ReaderUtil {
 
     /**
     * Reads a big-endian `i32`.
-    * 
+    *
     * `i32`s are 4 bytes long.
-    * 
+    *
     * # Examples
     *
     * None right now.
@@ -363,9 +363,9 @@ pub trait ReaderUtil {
 
     /**
     * Reads a big-endian `i16`.
-    * 
+    *
     * `i16`s are 2 bytes long.
-    * 
+    *
     * # Examples
     *
     * None right now.
@@ -374,9 +374,9 @@ pub trait ReaderUtil {
 
     /**
     * Reads a big-endian `f64`.
-    * 
+    *
     * `f64`s are 8 byte, IEEE754 double-precision floating point numbers.
-    * 
+    *
     * # Examples
     *
     * None right now.
@@ -385,9 +385,9 @@ pub trait ReaderUtil {
 
     /**
     * Reads a big-endian `f32`.
-    * 
+    *
     * `f32`s are 4 byte, IEEE754 single-precision floating point numbers.
-    * 
+    *
     * # Examples
     *
     * None right now.
@@ -396,9 +396,9 @@ pub trait ReaderUtil {
 
     /**
     * Reads a little-endian `u64`.
-    * 
+    *
     * `u64`s are 8 bytes long.
-    * 
+    *
     * # Examples
     *
     * None right now.
@@ -407,9 +407,9 @@ pub trait ReaderUtil {
 
     /**
     * Reads a little-endian `u32`.
-    * 
+    *
     * `u32`s are 4 bytes long.
-    * 
+    *
     * # Examples
     *
     * None right now.
@@ -418,9 +418,9 @@ pub trait ReaderUtil {
 
     /**
     * Reads a little-endian `u16`.
-    * 
+    *
     * `u16`s are 2 bytes long.
-    * 
+    *
     * # Examples
     *
     * None right now.
@@ -429,9 +429,9 @@ pub trait ReaderUtil {
 
     /**
     * Reads a little-endian `i64`.
-    * 
+    *
     * `i64`s are 8 bytes long.
-    * 
+    *
     * # Examples
     *
     * None right now.
@@ -440,9 +440,9 @@ pub trait ReaderUtil {
 
     /**
     * Reads a little-endian `i32`.
-    * 
+    *
     * `i32`s are 4 bytes long.
-    * 
+    *
     * # Examples
     *
     * None right now.
@@ -451,9 +451,9 @@ pub trait ReaderUtil {
 
     /**
     * Reads a little-endian `i16`.
-    * 
+    *
     * `i16`s are 2 bytes long.
-    * 
+    *
     * # Examples
     *
     * None right now.
@@ -462,9 +462,9 @@ pub trait ReaderUtil {
 
     /**
     * Reads a little-endian `f64`.
-    * 
+    *
     * `f64`s are 8 byte, IEEE754 double-precision floating point numbers.
-    * 
+    *
     * # Examples
     *
     * None right now.
@@ -473,9 +473,9 @@ pub trait ReaderUtil {
 
     /**
     * Reads a little-endian `f32`.
-    * 
+    *
     * `f32`s are 4 byte, IEEE754 single-precision floating point numbers.
-    * 
+    *
     * # Examples
     *
     * None right now.
@@ -483,10 +483,10 @@ pub trait ReaderUtil {
     fn read_le_f32(&self) -> f32;
 
     /**
-    * Read a u8. 
-    * 
+    * Read a u8.
+    *
     * `u8`s are 1 byte.
-    * 
+    *
     * # Examples
     *
     * None right now.
@@ -494,10 +494,10 @@ pub trait ReaderUtil {
     fn read_u8(&self) -> u8;
 
     /**
-    * Read an i8. 
-    * 
+    * Read an i8.
+    *
     * `i8`s are 1 byte.
-    * 
+    *
     * # Examples
     *
     * None right now.