Docs for ip, addrinfo modules. Ad more Option examples

src/libstd/io/net/addrinfo.rs

@@ -15,6 +15,20 @@ Synchronous DNS Resolution
 Contains the functionality to perform DNS resolution in a style related to
 getaddrinfo()
 
+
+# Examples
+
+```rust
+use std::io::net::addrinfo;
+
+fn main(){
+    let ips = addrinfo::get_host_addresses("rust-lang.org").unwrap();
+    for ip in ips.iter() {
+        println!("{}", ip);
+    }
+}
+```
+
 */
 
 #[allow(missing_doc)];
@@ -62,7 +76,10 @@ pub struct Hint {
     flags: uint,
 }
 
+/// This structure contains a result from a DNS lookup, the most important
+/// field being `address`.
 pub struct Info {
+    /// Socket address returned by DNS lookup
     address: SocketAddr,
     family: uint,
     socktype: Option<SocketType>,
@@ -72,6 +89,17 @@ pub struct Info {
 
 /// Easy name resolution. Given a hostname, returns the list of IP addresses for
 /// that hostname.
+///
+/// # Example
+///
+/// ```rust
+/// use std::io::net::addrinfo;
+///
+/// let ips = addrinfo::get_host_addresses("rust-lang.org").unwrap();
+/// for ip in ips.iter() {
+///     println!("{}", ip);
+/// }
+/// ```
 pub fn get_host_addresses(host: &str) -> IoResult<~[IpAddr]> {
     lookup(Some(host), None, None).map(|a| a.map(|i| i.address.ip))
 }

src/libstd/io/net/ip.rs

@@ -8,7 +8,22 @@
 // option. This file may not be copied, modified, or distributed
 // except according to those terms.
 
-#[allow(missing_doc)];
+/*!
+IP and socket addresses.
+
+# Examples
+
+```rust
+use std::io::net::ip::{SocketAddr, Ipv4Addr};
+
+let socket_address = SocketAddr {
+    ip: Ipv4Addr(127, 0, 0, 1),
+    port: 8080,
+};
+
+println!("{}", socket_address);
+```
+*/
 
 use container::Container;
 use fmt;
@@ -18,11 +33,15 @@ use option::{Option, None, Some};
 use str::StrSlice;
 use vec::{MutableCloneableVector, ImmutableVector, MutableVector};
 
+/// Network port, usually part of a SocketAddr struct
 pub type Port = u16;
 
+/// IP address. Either `Ipv4Addr` or `Ipv6Addr`.
 #[deriving(Eq, TotalEq, Clone, Hash)]
 pub enum IpAddr {
+    /// Represents an IPv4 address
     Ipv4Addr(u8, u8, u8, u8),
+    /// Represents an IPv6 address
     Ipv6Addr(u16, u16, u16, u16, u16, u16, u16, u16)
 }
 
@@ -51,9 +70,12 @@ impl fmt::Show for IpAddr {
     }
 }
 
+/// Network socket address
 #[deriving(Eq, TotalEq, Clone, Hash)]
 pub struct SocketAddr {
+    /// IP address. Either `Ipv4Addr` or `Ipv6Addr`.
     ip: IpAddr,
+    /// Network Port. Just a typedef to `u16`.
     port: Port,
 }
 

src/libstd/option.rs

@@ -19,7 +19,9 @@
 //! Options are most commonly used with pattern matching to query the presence
 //! of a value and take action, always accounting for the `None` case.
 //!
-//! # Example
+//! # Examples
+//!
+//! Basic usage:
 //!
 //! ```
 //! let msg = Some(~"howdy");
@@ -30,12 +32,45 @@
 //!     None => ()
 //! }
 //!
-//! // Remove the contained string, destroying the Option
+//! // Remove the contained string, destroying the `Option`
 //! let unwrapped_msg = match msg {
 //!     Some(m) => m,
 //!     None => ~"default message"
 //! };
 //! ```
+//!
+//! You don't have to always use a `match` statement, there are some methods
+//! for common use cases. Defaulting to a value, as in the above example, is
+//! one such case. It could be replaced with the following:
+//!
+//! ```rust
+//! let msg = Some(~"howdy");
+//! let unwrapped_msg = msg.unwrap_or(~"default message");
+//! ```
+//!
+//! For more complex use cases, the `and_then` method may be useful. It
+//! allows you to chain multiple functions that could return an `Option` as if
+//! they all contain a `Some(T)`, simply returning a `None` if any one
+//! `Option` in the chain contains `None`. Thus, `and_then` constitutes monadic
+//!  bind and can be much more compact than `match` statements:
+//!
+//! ```rust
+//! // Fake functions for demonstration purposes
+//! fn x () -> Option<u8> { Some(1) }
+//! fn y (x: u8) -> Option<u8> { Some(1 + x) }
+//! fn z (y: u8) -> Option<u8> { None }
+//!
+//! // By using `and_then`, we pass the unwrapped value returned by `x()` to
+//! // the function `y`, returning another `Option` for chaining.
+//! let res1 = x().and_then(y);
+//! println!("x and y: {}", res1);
+//!
+//! // We can chain on further calls to `z`. The first call returns `None`, but
+//! // calling `and_then` on it is still safe - `z` is not called again after the
+//! // first `None` is encountered.
+//! let res2 = x().and_then(y).and_then(z).and_then(z);
+//! println!("x and y and z and z: {}", res2);
+//! ```
 
 use any::Any;
 use clone::Clone;