Add doc examples for most untrusted::Input methods.

I agree to license my contributions to each file under the terms given
at the top of each file I changed.

src/untrusted.rs

@@ -93,6 +93,14 @@ pub struct Input<'a> {
 
 impl<'a> Input<'a> {
     /// Construct a new `Input` for the given input `bytes`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use untrusted::Input;
+    ///
+    /// let input = Input::from(b"foo");
+    /// ```
     pub fn from(bytes: &'a [u8]) -> Input<'a> {
         // This limit is important for avoiding integer overflow. In particular,
         // `Reader` assumes that an `i + 1 > i` if `input.value.get(i)` does
@@ -104,17 +112,70 @@ impl<'a> Input<'a> {
     }
 
     /// Returns `true` if the input is empty and false otherwise.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use untrusted::Input;
+    ///
+    /// let input = Input::from(b"");
+    /// assert!(input.is_empty());
+    ///
+    /// let input = Input::from(b"foo");
+    /// assert!(!input.is_empty());
+    /// ```
     #[inline]
     pub fn is_empty(&self) -> bool { self.value.len() == 0 }
 
     /// Returns the length of the `Input`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use untrusted::Input;
+    ///
+    /// let input = Input::from(b"foo");
+    /// assert_eq!(input.len(), 3);
+    /// ```
     #[inline]
     pub fn len(&self) -> usize { self.value.len() }
 
 
     /// Calls `read` with the given input as a `Reader`, ensuring that `read`
     /// consumed the entire input. If `read` does not consume the entire input,
     /// `incomplete_read` is returned.
+    ///
+    /// # Examples
+    ///
+    /// `read` consumes entire input:
+    ///
+    /// ```
+    /// use untrusted::Input;
+    ///
+    /// let input = Input::from(b"foo");
+    /// let result = input.read_all((), |input| {
+    ///     assert_eq!(b'f', try!(input.read_byte()));
+    ///     assert_eq!(b'o', try!(input.read_byte()));
+    ///     assert_eq!(b'o', try!(input.read_byte()));
+    ///     assert!(input.at_end());
+    ///     Ok(())
+    /// });
+    /// assert!(result.is_ok());
+    /// ```
+    ///
+    /// `read` does *not* consume entire input:
+    ///
+    /// ```
+    /// use untrusted::Input;
+    ///
+    /// let input = Input::from(b"foo");
+    /// let result = input.read_all((), |input| {
+    ///     assert_eq!(b'f', try!(input.read_byte()));
+    ///     assert!(!input.at_end());
+    ///     Ok(())
+    /// });
+    /// assert!(result.is_err());
+    /// ```
     pub fn read_all<F, R, E>(&self, incomplete_read: E, read: F)
                              -> Result<R, E>
                              where F: FnOnce(&mut Reader<'a>) -> Result<R, E> {
@@ -128,6 +189,22 @@ impl<'a> Input<'a> {
     }
 
     /// Like `read_all`, except taking an `FnMut`.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use untrusted::Input;
+    ///
+    /// let input = Input::from(b"foo");
+    /// let mut v = vec![];
+    /// let result = input.read_all((), |input| {
+    ///     v.push(try!(input.read_byte()));
+    ///     v.push(try!(input.read_byte()));
+    ///     v.push(try!(input.read_byte()));
+    ///     Ok(())
+    /// });
+    /// assert!(result.is_ok());
+    /// ```
     pub fn read_all_mut<F, R, E>(&self, incomplete_read: E, mut read: F)
                                  -> Result<R, E>
                                  where F: FnMut(&mut Reader<'a>)