---

yaml
---
r: 65082
b: refs/heads/master
c: 1065a92
h: refs/heads/master
v: v3

Author: steveklabnik

[refs]

@@ -1,5 +1,5 @@
 ---
-refs/heads/master: 929050de73c1edb22211fa05e891068fe9a1a0d2
+refs/heads/master: 1065a92bf3bbe1f4bb11b7b7268a91529bbf8f89
 refs/heads/snap-stage1: e33de59e47c5076a89eadeb38f4934f58a3618a6
 refs/heads/snap-stage3: 18e3db7392d2d0697b7e27d6d986139960144d85
 refs/heads/try: 7b78b52e602bb3ea8174f9b2006bff3315f03ef9

trunk/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.
@@ -1561,57 +1571,13 @@ pub fn buffered_file_writer(path: &Path) -> Result<@Writer, ~str> {
 // FIXME (#2004) it would be great if this could be a const
 // FIXME (#2004) why are these different from the way stdin() is
 // implemented?
-
-
-/**
-* Gives a `Writer` which allows you to write to the standard output.
-*
-* # Examples
-* ~~~
-* let stdout = core::io::stdout();
-* stdout.write_str("hello\n");
-* ~~~
-*/
 pub fn stdout() -> @Writer { fd_writer(libc::STDOUT_FILENO as c_int, false) }
-
-/**
-* Gives a `Writer` which allows you to write to standard error.
-*
-* # Examples
-* ~~~
-* let stderr = core::io::stderr();
-* stderr.write_str("hello\n");
-* ~~~
-*/
 pub fn stderr() -> @Writer { fd_writer(libc::STDERR_FILENO as c_int, false) }
 
-/**
-* Prints a string to standard output.
-* 
-* This string will not have an implicit newline at the end. If you want
-* an implicit newline, please see `println`.
-*
-* # Examples
-* ~~~
-* // print is imported into the prelude, and so is always available.
-* print("hello");
-* ~~~
-*/
 pub fn print(s: &str) {
     stdout().write_str(s);
 }
 
-/**
-* Prints a string to standard output, followed by a newline.
-* 
-* If you do not want an implicit newline, please see `print`.
-*
-* # Examples
-* ~~~
-* // println is imported into the prelude, and so is always available.
-* println("hello");
-* ~~~
-*/
 pub fn println(s: &str) {
     stdout().write_line(s);
 }