std: Touch various I/O documentation blocks

These are mostly touchups from the previous commit.

4 files changed, 39 insertions, 17 deletions

diff --git a/src/libstd/io/mod.rs b/src/libstd/io/mod.rs
index 3f959a8f780..3e193f246a8 100644
--- a/src/libstd/io/mod.rs
+++ b/src/libstd/io/mod.rs
@@ -302,7 +302,6 @@ 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,
@@ -1428,7 +1427,6 @@ 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)]
 #[deriving(Hash)]
 pub struct UnstableFileStat {
     /// The ID of the device containing the file.
diff --git a/src/libstd/io/net/udp.rs b/src/libstd/io/net/udp.rs
index eabd00a6a2d..95241813257 100644
--- a/src/libstd/io/net/udp.rs
+++ b/src/libstd/io/net/udp.rs
@@ -14,8 +14,6 @@
 //! 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};
@@ -24,6 +22,36 @@ use io::{Reader, Writer, IoResult};
 use rt::rtio::{RtioSocket, RtioUdpSocket, IoFactory, LocalIo};
 
 /// A User Datagram Protocol socket.
+///
+/// This is an implementation of a bound UDP socket. This supports both IPv4 and
+/// IPv6 addresses, and there is no corresponding notion of a server because UDP
+/// is a datagram protocol.
+///
+/// # Example
+///
+/// ```rust,no_run
+/// # #[allow(unused_must_use)];
+/// use std::io::net::udp::UdpSocket;
+/// use std::io::net::ip::{Ipv4Addr, SocketAddr};
+///
+/// let addr = SocketAddr { ip: Ipv4Addr(127, 0, 0, 1), port: 34254 };
+/// let mut socket = match UdpSocket::bind(addr) {
+///     Ok(s) => s,
+///     Err(e) => fail!("couldn't bind socket: {}", e),
+/// };
+///
+/// let mut buf = [0, ..10];
+/// match socket.recvfrom(buf) {
+///     Ok((amt, src)) => {
+///         // Send a reply to the socket we received data from
+///         let buf = buf.mut_slice_to(amt);
+///         buf.reverse();
+///         socket.sendto(buf, src);
+///     }
+///     Err(e) => println!("couldn't receive a datagram: {}", e)
+/// }
+/// drop(socket); // close the socket
+/// ```
 pub struct UdpSocket {
     priv obj: ~RtioUdpSocket
 }
diff --git a/src/libstd/num/mod.rs b/src/libstd/num/mod.rs
index 31124db49b9..202e26e2c93 100644
--- a/src/libstd/num/mod.rs
+++ b/src/libstd/num/mod.rs
@@ -340,11 +340,11 @@ pub enum FPCategory {
 }
 
 /// Operations on primitive floating point numbers.
-///
-/// TODO(#5527): In a future version of Rust, many of these functions will become constants.
-///
-/// FIXME(#8888): Several of these functions have a parameter named `unused_self`. Removing it
-/// requires #8888 to be fixed.
+// FIXME(#5527): In a future version of Rust, many of these functions will
+//               become constants.
+//
+// FIXME(#8888): Several of these functions have a parameter named
+//               `unused_self`. Removing it requires #8888 to be fixed.
 pub trait Float: Signed + Round + Primitive {
     /// Returns the maximum of the two numbers.
     fn max(self, other: Self) -> Self;
diff --git a/src/libstd/os.rs b/src/libstd/os.rs
index 3d05414c625..eeebede6c58 100644
--- a/src/libstd/os.rs
+++ b/src/libstd/os.rs
@@ -367,18 +367,16 @@ pub fn unsetenv(n: &str) {
 }
 
 /// A low-level OS in-memory pipe.
-///
-/// This type is deprecated in favor of the types in `std::io::pipe`.
 pub struct Pipe {
-    /// A file descriptor representing the input end of the pipe.
+    /// A file descriptor representing the reading end of the pipe. Data written
+    /// on the `out` file descriptor can be read from this file descriptor.
     input: c_int,
-    /// A file descriptor representing the output end of the pipe.
+    /// A file descriptor representing the write end of the pipe. Data written
+    /// to this file descriptor can be read from the `input` file descriptor.
     out: c_int,
 }
 
 /// Creates a new low-level OS in-memory pipe.
-///
-/// This function is deprecated in favor of the types in `std::io::pipe`.
 #[cfg(unix)]
 pub fn pipe() -> Pipe {
     unsafe {
@@ -390,8 +388,6 @@ pub fn pipe() -> Pipe {
 }
 
 /// Creates a new low-level OS in-memory pipe.
-///
-/// This function is deprecated in favor of the types in `std::io::pipe`.
 #[cfg(windows)]
 pub fn pipe() -> Pipe {
     unsafe {