libstd: Document the following modules:

* native::io
* std::char
* std::fmt
* std::fmt::parse
* std::io
* std::io::extensions
* std::io::net::ip
* std::io::net::udp
* std::io::net::unix
* std::io::pipe
* std::num
* std::num::f32
* std::num::f64
* std::num::strconv
* std::os

6 files changed, 128 insertions, 14 deletions

diff --git a/src/libstd/io/extensions.rs b/src/libstd/io/extensions.rs
index e5938569ea3..b9e933d0b14 100644
--- a/src/libstd/io/extensions.rs
+++ b/src/libstd/io/extensions.rs
@@ -42,8 +42,11 @@ pub struct Bytes<'r, T> {
 }
 
 impl<'r, R: Reader> Bytes<'r, R> {
+    /// Constructs a new byte iterator from the given Reader instance.
     pub fn new(r: &'r mut R) -> Bytes<'r, R> {
-        Bytes { reader: r }
+        Bytes {
+            reader: r,
+        }
     }
 }
 
@@ -58,6 +61,20 @@ impl<'r, R: Reader> Iterator<IoResult<u8>> for Bytes<'r, R> {
     }
 }
 
+/// Converts an 8-bit to 64-bit unsigned value to a little-endian byte
+/// representation of the given size. If the size is not big enough to
+/// represent the value, then the high-order bytes are truncated.
+///
+/// Arguments:
+///
+/// * `n`: The value to convert.
+/// * `size`: The size of the value, in bytes. This must be 8 or less, or task
+///           failure occurs. If this is less than 8, then a value of that
+///           many bytes is produced. For example, if `size` is 4, then a
+///           32-bit byte representation is produced.
+/// * `f`: A callback that receives the value.
+///
+/// This function returns the value returned by the callback, for convenience.
 pub fn u64_to_le_bytes<T>(n: u64, size: uint, f: |v: &[u8]| -> T) -> T {
     use mem::{to_le16, to_le32, to_le64};
     use cast::transmute;
@@ -84,6 +101,20 @@ pub fn u64_to_le_bytes<T>(n: u64, size: uint, f: |v: &[u8]| -> T) -> T {
     }
 }
 
+/// Converts an 8-bit to 64-bit unsigned value to a big-endian byte
+/// representation of the given size. If the size is not big enough to
+/// represent the value, then the high-order bytes are truncated.
+///
+/// Arguments:
+///
+/// * `n`: The value to convert.
+/// * `size`: The size of the value, in bytes. This must be 8 or less, or task
+///           failure occurs. If this is less than 8, then a value of that
+///           many bytes is produced. For example, if `size` is 4, then a
+///           32-bit byte representation is produced.
+/// * `f`: A callback that receives the value.
+///
+/// This function returns the value returned by the callback, for convenience.
 pub fn u64_to_be_bytes<T>(n: u64, size: uint, f: |v: &[u8]| -> T) -> T {
     use mem::{to_be16, to_be32, to_be64};
     use cast::transmute;
@@ -108,10 +139,18 @@ pub fn u64_to_be_bytes<T>(n: u64, size: uint, f: |v: &[u8]| -> T) -> T {
     }
 }
 
-pub fn u64_from_be_bytes(data: &[u8],
-                         start: uint,
-                         size: uint)
-                      -> u64 {
+/// Extracts an 8-bit to 64-bit unsigned big-endian value from the given byte
+/// buffer and returns it as a 64-bit value.
+///
+/// Arguments:
+///
+/// * `data`: The buffer in which to extract the value.
+/// * `start`: The offset at which to extract the value.
+/// * `size`: The size of the value in bytes to extract. This must be 8 or
+///           less, or task failure occurs. If this is less than 8, then only
+///           that many bytes are parsed. For example, if `size` is 4, then a
+///           32-bit value is parsed.
+pub fn u64_from_be_bytes(data: &[u8], start: uint, size: uint) -> u64 {
     use ptr::{copy_nonoverlapping_memory};
     use mem::from_be64;
     use slice::MutableVector;
diff --git a/src/libstd/io/mod.rs b/src/libstd/io/mod.rs
index 6bd8f119ba2..3f959a8f780 100644
--- a/src/libstd/io/mod.rs
+++ b/src/libstd/io/mod.rs
@@ -300,25 +300,45 @@ impl fmt::Show for IoError {
     }
 }
 
+/// A list specifying general categories of I/O error.
 #[deriving(Eq, Clone, Show)]
 #[allow(missing_doc)]
 pub enum IoErrorKind {
+    /// Any I/O error not part of this list.
     OtherIoError,
+    /// The operation could not complete because end of file was reached.
     EndOfFile,
+    /// The file was not found.
     FileNotFound,
+    /// The file permissions disallowed access to this file.
     PermissionDenied,
+    /// A network connection failed for some reason not specified in this list.
     ConnectionFailed,
+    /// The network operation failed because the network connection was cloesd.
     Closed,
+    /// The connection was refused by the remote server.
     ConnectionRefused,
+    /// The connection was reset by the remote server.
     ConnectionReset,
+    /// The connection was aborted (terminated) by the remote server.
     ConnectionAborted,
+    /// The network operation failed because it was not connected yet.
     NotConnected,
+    /// The operation failed because a pipe was closed.
     BrokenPipe,
+    /// A file already existed with that name.
     PathAlreadyExists,
+    /// No file exists at that location.
     PathDoesntExist,
+    /// The path did not specify the type of file that this operation required. For example,
+    /// attempting to copy a directory with the `fs::copy()` operation will fail with this error.
     MismatchedFileTypeForOperation,
+    /// The operation temporarily failed (for example, because a signal was received), and retrying
+    /// may succeed.
     ResourceUnavailable,
+    /// No I/O functionality is available for this task.
     IoUnavailable,
+    /// A parameter was incorrect in a way that caused an I/O error not part of this list.
     InvalidInput,
 }
 
@@ -1411,15 +1431,25 @@ pub struct FileStat {
 #[allow(missing_doc)]
 #[deriving(Hash)]
 pub struct UnstableFileStat {
+    /// The ID of the device containing the file.
     device: u64,
+    /// The file serial number.
     inode: u64,
+    /// The device ID.
     rdev: u64,
+    /// The number of hard links to this file.
     nlink: u64,
+    /// The user ID of the file.
     uid: u64,
+    /// The group ID of the file.
     gid: u64,
+    /// The optimal block size for I/O.
     blksize: u64,
+    /// The blocks allocated for this file.
     blocks: u64,
+    /// User-defined flags for the file.
     flags: u64,
+    /// The file generation number.
     gen: u64,
 }
 
diff --git a/src/libstd/io/net/ip.rs b/src/libstd/io/net/ip.rs
index dc24ead6258..fef4dd380e8 100644
--- a/src/libstd/io/net/ip.rs
+++ b/src/libstd/io/net/ip.rs
@@ -8,6 +8,11 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
+//! Internet Protocol (IP) addresses.
+//!
+//! This module contains functions useful for parsing, formatting, and
+//! manipulating IP addresses.
+
 #[allow(missing_doc)];
 
 use container::Container;
diff --git a/src/libstd/io/net/udp.rs b/src/libstd/io/net/udp.rs
index e2620556321..eabd00a6a2d 100644
--- a/src/libstd/io/net/udp.rs
+++ b/src/libstd/io/net/udp.rs
@@ -8,7 +8,14 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-#[allow(missing_doc)];
+//! UDP (User Datagram Protocol) network connections.
+//!
+//! This module contains the ability to open a UDP stream to a socket address.
+//! The destination and binding addresses can either be an IPv4 or IPv6
+//! address. There is no corresponding notion of a server because UDP is a
+//! datagram protocol.
+//!
+//! A UDP connection implements the `Reader` and `Writer` traits.
 
 use clone::Clone;
 use result::{Ok, Err};
@@ -16,58 +23,85 @@ use io::net::ip::SocketAddr;
 use io::{Reader, Writer, IoResult};
 use rt::rtio::{RtioSocket, RtioUdpSocket, IoFactory, LocalIo};
 
+/// A User Datagram Protocol socket.
 pub struct UdpSocket {
     priv obj: ~RtioUdpSocket
 }
 
 impl UdpSocket {
+    /// Creates a UDP socket from the given socket address.
     pub fn bind(addr: SocketAddr) -> IoResult<UdpSocket> {
         LocalIo::maybe_raise(|io| {
             io.udp_bind(addr).map(|s| UdpSocket { obj: s })
         })
     }
 
-    pub fn recvfrom(&mut self, buf: &mut [u8]) -> IoResult<(uint, SocketAddr)> {
+    /// Receives data from the socket. On success, returns the number of bytes
+    /// read and the address from whence the data came.
+    pub fn recvfrom(&mut self, buf: &mut [u8])
+                    -> IoResult<(uint, SocketAddr)> {
         self.obj.recvfrom(buf)
     }
 
+    /// Sends data on the socket to the given address. Returns nothing on
+    /// success.
     pub fn sendto(&mut self, buf: &[u8], dst: SocketAddr) -> IoResult<()> {
         self.obj.sendto(buf, dst)
     }
 
+    /// Creates a `UdpStream`, which allows use of the `Reader` and `Writer`
+    /// traits to receive and send data from the same address. This transfers
+    /// ownership of the socket to the stream.
+    ///
+    /// Note that this call does not perform any actual network communication,
+    /// because UDP is a datagram protocol.
     pub fn connect(self, other: SocketAddr) -> UdpStream {
-        UdpStream { socket: self, connected_to: other }
+        UdpStream {
+            socket: self,
+            connected_to: other,
+        }
     }
 
+    /// Returns the socket address that this socket was created from.
     pub fn socket_name(&mut self) -> IoResult<SocketAddr> {
         self.obj.socket_name()
     }
 }
 
 impl Clone for UdpSocket {
-    /// Creates a new handle to this UDP socket, allowing for simultaneous reads
-    /// and writes of the socket.
+    /// Creates a new handle to this UDP socket, allowing for simultaneous
+    /// reads and writes of the socket.
     ///
     /// The underlying UDP socket will not be closed until all handles to the
-    /// socket have been deallocated. Two concurrent reads will not receive the
-    /// same data.  Instead, the first read will receive the first packet
+    /// socket have been deallocated. Two concurrent reads will not receive
+    /// the same data. Instead, the first read will receive the first packet
     /// received, and the second read will receive the second packet.
     fn clone(&self) -> UdpSocket {
-        UdpSocket { obj: self.obj.clone() }
+        UdpSocket {
+            obj: self.obj.clone(),
+        }
     }
 }
 
+/// A type that allows convenient usage of a UDP stream connected to one
+/// address via the `Reader` and `Writer` traits.
 pub struct UdpStream {
     priv socket: UdpSocket,
     priv connected_to: SocketAddr
 }
 
 impl UdpStream {
+    /// Allows access to the underlying UDP socket owned by this stream. This
+    /// is useful to, for example, use the socket to send data to hosts other
+    /// than the one that this stream is connected to.
     pub fn as_socket<T>(&mut self, f: |&mut UdpSocket| -> T) -> T {
         f(&mut self.socket)
     }
 
-    pub fn disconnect(self) -> UdpSocket { self.socket }
+    /// Consumes this UDP stream and returns out the underlying socket.
+    pub fn disconnect(self) -> UdpSocket {
+        self.socket
+    }
 }
 
 impl Reader for UdpStream {
diff --git a/src/libstd/io/net/unix.rs b/src/libstd/io/net/unix.rs
index bd715858a01..9f04317a5c8 100644
--- a/src/libstd/io/net/unix.rs
+++ b/src/libstd/io/net/unix.rs
@@ -79,7 +79,9 @@ impl Writer for UnixStream {
     fn write(&mut self, buf: &[u8]) -> IoResult<()> { self.obj.write(buf) }
 }
 
+/// A value that can listen for incoming named pipe connection requests.
 pub struct UnixListener {
+    /// The internal, opaque runtime Unix listener.
     priv obj: ~RtioUnixListener,
 }
 
@@ -119,7 +121,9 @@ impl Listener<UnixStream, UnixAcceptor> for UnixListener {
     }
 }
 
+/// A value that can accept named pipe connections, returned from `listen()`.
 pub struct UnixAcceptor {
+    /// The internal, opaque runtime Unix acceptor.
     priv obj: ~RtioUnixAcceptor,
 }
 
diff --git a/src/libstd/io/pipe.rs b/src/libstd/io/pipe.rs
index 02dfaeb7164..9984a3e5cdf 100644
--- a/src/libstd/io/pipe.rs
+++ b/src/libstd/io/pipe.rs
@@ -20,7 +20,9 @@ use io::IoResult;
 use libc;
 use rt::rtio::{RtioPipe, LocalIo};
 
+/// A synchronous, in-memory pipe.
 pub struct PipeStream {
+    /// The internal, opaque runtime pipe object.
     priv obj: ~RtioPipe,
 }