auto merge of #12607 : alexcrichton/rust/io++, r=brson

This lowers the #[allow(missing_doc)] directive into some of the lower modules
which are less mature. Most I/O modules now require comprehensive documentation.

src/libstd/io/comm_adapters.rs

@@ -42,6 +42,7 @@ pub struct PortReader {
 }
 
 impl PortReader {
+    /// Wraps a `Port` in a `PortReader` structure
     pub fn new(port: Port<~[u8]>) -> PortReader {
         PortReader {
             buf: None,
@@ -96,10 +97,11 @@ impl Reader for PortReader {
 /// writer.write("hello, world".as_bytes());
 /// ```
 pub struct ChanWriter {
-    chan: Chan<~[u8]>,
+    priv chan: Chan<~[u8]>,
 }
 
 impl ChanWriter {
+    /// Wraps a channel in a `ChanWriter` structure
     pub fn new(chan: Chan<~[u8]>) -> ChanWriter {
         ChanWriter { chan: chan }
     }

src/libstd/io/extensions.rs

@@ -10,6 +10,8 @@
 
 //! Utility mixins that apply to all Readers and Writers
 
+#[allow(missing_doc)];
+
 // FIXME: Not sure how this should be structured
 // FIXME: Iteration should probably be considered separately
 

src/libstd/io/mem.rs

@@ -224,6 +224,8 @@ pub struct BufWriter<'a> {
 }
 
 impl<'a> BufWriter<'a> {
+    /// Creates a new `BufWriter` which will wrap the specified buffer. The
+    /// writer initially starts at position 0.
     pub fn new<'a>(buf: &'a mut [u8]) -> BufWriter<'a> {
         BufWriter {
             buf: buf,

src/libstd/io/mod.rs

@@ -174,7 +174,6 @@ will also return an error.
 
 */
 
-#[allow(missing_doc)];
 #[deny(unused_must_use)];
 
 use cast;
@@ -247,6 +246,7 @@ mod comm_adapters;
 // https://groups.google.com/forum/#!topic/libuv/oQO1HJAIDdA
 static DEFAULT_BUF_SIZE: uint = 1024 * 64;
 
+/// A convenient typedef of the return value of any I/O action.
 pub type IoResult<T> = Result<T, IoError>;
 
 /// The type passed to I/O condition handlers to indicate error
@@ -256,8 +256,12 @@ pub type IoResult<T> = Result<T, IoError>;
 /// Is something like this sufficient? It's kind of archaic
 #[deriving(Eq, Clone)]
 pub struct IoError {
+    /// An enumeration which can be matched against for determining the flavor
+    /// of error.
     kind: IoErrorKind,
+    /// A human-readable description about the error
     desc: &'static str,
+    /// Detailed information about this error, not always available
     detail: Option<~str>
 }
 
@@ -272,6 +276,7 @@ impl fmt::Show for IoError {
 }
 
 #[deriving(Eq, Clone, Show)]
+#[allow(missing_doc)]
 pub enum IoErrorKind {
     OtherIoError,
     EndOfFile,
@@ -292,6 +297,13 @@ pub enum IoErrorKind {
     InvalidInput,
 }
 
+/// A trait for objects which are byte-oriented streams. Readers are defined by
+/// one method, `read`. This function will block until data is available,
+/// filling in the provided buffer with any data read.
+///
+/// Readers are intended to be composable with one another. Many objects
+/// throughout the I/O and related libraries take and provide types which
+/// implement the `Reader` trait.
 pub trait Reader {
 
     // Only method which need to get implemented for this trait
@@ -655,8 +667,33 @@ impl<'a> Reader for &'a mut Reader {
     fn read(&mut self, buf: &mut [u8]) -> IoResult<uint> { self.read(buf) }
 }
 
+/// A `RefReader` is a struct implementing `Reader` which contains a reference
+/// to another reader. This is often useful when composing streams.
+///
+/// # Example
+///
+/// ```
+/// # fn main() {}
+/// # fn process_input<R: Reader>(r: R) {}
+/// # fn foo() {
+/// use std::io;
+/// use std::io::util::LimitReader;
+///
+/// let mut stream = io::stdin();
+///
+/// // Only allow the function to process at most one kilobyte of input
+/// {
+///     let stream = LimitReader::new(stream.by_ref(), 1024);
+///     process_input(stream);
+/// }
+///
+/// // 'stream' is still available for use here
+///
+/// # }
+/// ```
 pub struct RefReader<'a, R> {
-    priv inner: &'a mut R
+    /// The underlying reader which this is referencing
+    inner: &'a mut R
 }
 
 impl<'a, R: Reader> Reader for RefReader<'a, R> {
@@ -668,6 +705,16 @@ fn extend_sign(val: u64, nbytes: uint) -> i64 {
     (val << shift) as i64 >> shift
 }
 
+/// A trait for objects which are byte-oriented streams. Writers are defined by
+/// one method, `write`. This function will block until the provided buffer of
+/// bytes has been entirely written, and it will return any failurs which occur.
+///
+/// Another commonly overriden method is the `flush` method for writers such as
+/// buffered writers.
+///
+/// Writers are intended to be composable with one another. Many objects
+/// throughout the I/O and related libraries take and provide types which
+/// implement the `Writer` trait.
 pub trait Writer {
     /// Write the entirety of a given buffer
     ///
@@ -863,7 +910,32 @@ impl<'a> Writer for &'a mut Writer {
     fn flush(&mut self) -> IoResult<()> { self.flush() }
 }
 
+/// A `RefWriter` is a struct implementing `Writer` which contains a reference
+/// to another writer. This is often useful when composing streams.
+///
+/// # Example
+///
+/// ```
+/// # fn main() {}
+/// # fn process_input<R: Reader>(r: R) {}
+/// # fn foo () {
+/// use std::io::util::TeeReader;
+/// use std::io::{stdin, MemWriter};
+///
+/// let mut output = MemWriter::new();
+///
+/// {
+///     // Don't give ownership of 'output' to the 'tee'. Instead we keep a
+///     // handle to it in the outer scope
+///     let mut tee = TeeReader::new(stdin(), output.by_ref());
+///     process_input(tee);
+/// }
+///
+/// println!("input processed: {}", output.unwrap());
+/// # }
+/// ```
 pub struct RefWriter<'a, W> {
+    /// The underlying writer which this is referencing
     inner: &'a mut W
 }
 
@@ -873,6 +945,8 @@ impl<'a, W: Writer> Writer for RefWriter<'a, W> {
 }
 
 
+/// A Stream is a readable and a writable object. Data written is typically
+/// received by the object which reads receive data from.
 pub trait Stream: Reader + Writer { }
 
 impl<T: Reader + Writer> Stream for T {}
@@ -1070,7 +1144,8 @@ pub trait Buffer: Reader {
         }
     }
 
-    /// Create an iterator that reads a utf8-encoded character on each iteration until EOF.
+    /// Create an iterator that reads a utf8-encoded character on each iteration
+    /// until EOF.
     ///
     /// # Error
     ///
@@ -1082,6 +1157,8 @@ pub trait Buffer: Reader {
     }
 }
 
+/// When seeking, the resulting cursor is offset from a base by the offset given
+/// to the `seek` function. The base used is specified by this enumeration.
 pub enum SeekStyle {
     /// Seek from the beginning of the stream
     SeekSet,
@@ -1091,6 +1168,9 @@ pub enum SeekStyle {
     SeekCur,
 }
 
+/// An object implementing `Seek` internally has some form of cursor which can
+/// be moved within a stream of bytes. The stream typically has a fixed size,
+/// allowing seeking relative to either end.
 pub trait Seek {
     /// Return position of file cursor in the stream
     fn tell(&self) -> IoResult<u64>;
@@ -1157,6 +1237,17 @@ impl<'a, T, A: Acceptor<T>> Iterator<IoResult<T>> for IncomingConnections<'a, A>
     }
 }
 
+/// Creates a standard error for a commonly used flavor of error. The `detail`
+/// field of the returned error will always be `None`.
+///
+/// # Example
+///
+/// ```
+/// use std::io;
+///
+/// let eof = io::standard_error(io::EndOfFile);
+/// let einval = io::standard_error(io::InvalidInput);
+/// ```
 pub fn standard_error(kind: IoErrorKind) -> IoError {
     let desc = match kind {
         EndOfFile => "end of file",
@@ -1171,14 +1262,6 @@ pub fn standard_error(kind: IoErrorKind) -> IoError {
     }
 }
 
-pub fn placeholder_error() -> IoError {
-    IoError {
-        kind: OtherIoError,
-        desc: "Placeholder error. You shouldn't be seeing this",
-        detail: None
-    }
-}
-
 /// A mode specifies how a file should be opened or created. These modes are
 /// passed to `File::open_mode` and are used to control where the file is
 /// positioned when it is initially opened.
@@ -1194,22 +1277,53 @@ pub enum FileMode {
 /// Access permissions with which the file should be opened. `File`s
 /// opened with `Read` will return an error if written to.
 pub enum FileAccess {
+    /// Read-only access, requests to write will result in an error
     Read,
+    /// Write-only access, requests to read will result in an error
     Write,
+    /// Read-write access, no requests are denied by default
     ReadWrite,
 }
 
 /// Different kinds of files which can be identified by a call to stat
 #[deriving(Eq)]
 pub enum FileType {
+    /// This is a normal file, corresponding to `S_IFREG`
     TypeFile,
+
+    /// This file is a directory, corresponding to `S_IFDIR`
     TypeDirectory,
+
+    /// This file is a named pipe, corresponding to `S_IFIFO`
     TypeNamedPipe,
+
+    /// This file is a block device, corresponding to `S_IFBLK`
     TypeBlockSpecial,
+
+    /// This file is a symbolic link to another file, corresponding to `S_IFLNK`
     TypeSymlink,
+
+    /// The type of this file is not recognized as one of the other categories
     TypeUnknown,
 }
 
+/// A structure used to describe metadata information about a file. This
+/// structure is created through the `stat` method on a `Path`.
+///
+/// # Example
+///
+/// ```
+/// # fn main() {}
+/// # fn foo() {
+/// let info = match Path::new("foo.txt").stat() {
+///     Ok(stat) => stat,
+///     Err(e) => fail!("couldn't read foo.txt: {}", e),
+/// };
+///
+/// println!("path: {}", info.path.display());
+/// println!("byte size: {}", info.size);
+/// # }
+/// ```
 pub struct FileStat {
     /// The path that this stat structure is describing
     path: Path,
@@ -1250,6 +1364,7 @@ pub struct FileStat {
 /// structure. This information is not necessarily platform independent, and may
 /// have different meanings or no meaning at all on some platforms.
 #[unstable]
+#[allow(missing_doc)]
 pub struct UnstableFileStat {
     device: u64,
     inode: u64,

src/libstd/io/net/addrinfo.rs

@@ -17,6 +17,8 @@ getaddrinfo()
 
 */
 
+#[allow(missing_doc)];
+
 use io::IoResult;
 use io::net::ip::{SocketAddr, IpAddr};
 use option::{Option, Some, None};

src/libstd/io/net/ip.rs

@@ -8,6 +8,8 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+#[allow(missing_doc)];
+
 use container::Container;
 use fmt;
 use from_str::FromStr;

src/libstd/io/net/mod.rs

@@ -8,6 +8,8 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+//! Networking I/O
+
 pub use self::addrinfo::get_host_addresses;
 
 pub mod addrinfo;

src/libstd/io/net/udp.rs

@@ -8,6 +8,8 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+#[allow(missing_doc)];
+
 use clone::Clone;
 use result::{Ok, Err};
 use io::net::ip::SocketAddr;

src/libstd/io/net/unix.rs

@@ -22,6 +22,8 @@ instances as clients.
 
 */
 
+#[allow(missing_doc)];
+
 use prelude::*;
 
 use c_str::ToCStr;

src/libstd/io/pipe.rs

@@ -13,6 +13,8 @@
 //! Currently these aren't particularly useful, there only exists bindings
 //! enough so that pipes can be created to child processes.
 
+#[allow(missing_doc)];
+
 use prelude::*;
 use io::IoResult;
 use libc;
@@ -46,6 +48,7 @@ impl PipeStream {
         })
     }
 
+    #[doc(hidden)]
     pub fn new(inner: ~RtioPipe) -> PipeStream {
         PipeStream { obj: inner }
     }

src/libstd/io/signal.rs

@@ -29,6 +29,7 @@ use result::{Ok, Err};
 use rt::rtio::{IoFactory, LocalIo, RtioSignal};
 use vec::{ImmutableVector, OwnedVector};
 
+/// Signals that can be sent and received
 #[repr(int)]
 #[deriving(Eq, Hash)]
 pub enum Signum {

src/libstd/io/test.rs

@@ -121,6 +121,7 @@ fn base_port() -> u16 {
     return final_base;
 }
 
+/// Raises the file descriptor limit when running tests if necessary
 pub fn raise_fd_limit() {
     unsafe { darwin_fd_limit::raise_fd_limit() }
 }

src/libstd/io/timer.rs

@@ -15,33 +15,52 @@ Synchronous Timers
 This module exposes the functionality to create timers, block the current task,
 and create ports which will receive notifications after a period of time.
 
-# Example
-
-```rust,ignore
-
-use std::io::Timer;
-
-let mut timer = Timer::new().unwrap();
-timer.sleep(10); // block the task for awhile
-
-let timeout = timer.oneshot(10);
-// do some work
-timeout.recv(); // wait for the timeout to expire
-
-let periodic = timer.periodic(10);
-loop {
-    periodic.recv();
-    // this loop is only executed once every 10ms
-}
-
-```
-
 */
 
 use comm::Port;
 use rt::rtio::{IoFactory, LocalIo, RtioTimer};
 use io::IoResult;
 
+/// A synchronous timer object
+///
+/// Values of this type can be used to put the current task to sleep for a
+/// period of time. Handles to this timer can also be created in the form of
+/// ports which will receive notifications over time.
+///
+/// # Example
+///
+/// ```
+/// # fn main() {}
+/// # fn foo() {
+/// use std::io::Timer;
+///
+/// let mut timer = Timer::new().unwrap();
+/// timer.sleep(10); // block the task for awhile
+///
+/// let timeout = timer.oneshot(10);
+/// // do some work
+/// timeout.recv(); // wait for the timeout to expire
+///
+/// let periodic = timer.periodic(10);
+/// loop {
+///     periodic.recv();
+///     // this loop is only executed once every 10ms
+/// }
+/// # }
+/// ```
+///
+/// If only sleeping is necessary, then a convenience api is provided through
+/// the `io::timer` module.
+///
+/// ```
+/// # fn main() {}
+/// # fn foo() {
+/// use std::io::timer;
+///
+/// // Put this task to sleep for 5 seconds
+/// timer::sleep(5000);
+/// # }
+/// ```
 pub struct Timer {
     priv obj: ~RtioTimer
 }