Add more documentation

src/bytes.rs

@@ -6,6 +6,7 @@ use core::nonzero::NonZero;
 
 const INLINE: usize = 1;
 
+/// A specialized `ByteStr` box.
 #[unsafe_no_drop_flag]
 pub struct Bytes {
     vtable: NonZero<usize>,
@@ -252,92 +253,6 @@ impl<B: ByteStr + 'static> ByteStrPriv for B {
     }
 }
 
-/*
-impl ops::Index<usize> for Bytes {
-    type Output = u8;
-
-    fn index(&self, index: &usize) -> &u8 {
-        self.bytes.index(index)
-    }
-}
-
-impl PartialEq<Bytes> for Bytes {
-    fn eq(&self, other: &Bytes) -> bool {
-        let mut i1 = self.iter();
-        let mut i2 = other.iter();
-
-        loop {
-            let el = i1.next();
-
-            if el != i2.next() {
-                return false;
-            }
-
-            if el.is_none() {
-                return true;
-            }
-        }
-    }
-}
-
-pub struct BytesIter<'a> {
-    bytes: &'a Bytes,
-    pos: usize,
-}
-
-impl<'a> Iterator for BytesIter<'a> {
-    type Item = u8;
-
-    fn next(&mut self) -> Option<u8> {
-        if self.pos == self.bytes.len() {
-            return None;
-        }
-
-        let ret = self.bytes[self.pos];
-        self.pos += 1;
-        Some(ret)
-    }
-}
-
-#[cfg(test)]
-mod test {
-    use super::Bytes;
-
-    #[test]
-    pub fn test_accessing_bytes() {
-        let bytes = from_slice(b"foo");
-
-        for i in 0..3us {
-            assert_eq!(b"foo"[i], bytes[i]);
-        }
-    }
-
-    /*
-     *
-     * ===== Equality =====
-     *
-     */
-
-    #[test]
-    pub fn test_literal_bytes_eq() {
-        assert!(from_slice(b"foo") == from_slice(b"foo"));
-        assert!(from_slice(b"foo") != from_slice(b"bar"));
-        assert!(from_slice(b"foo") != from_slice(b"foo*"));
-        assert!(from_slice(b"foo*") != from_slice(b"foo"));
-    }
-
-    /*
-     *
-     * ===== Helpers =====
-     *
-     */
-
-    fn from_slice(bytes: &[u8]) -> Bytes {
-        Bytes::from_slice(bytes)
-    }
-}
-*/
-
 #[test]
 pub fn test_size_of() {
     let expect = mem::size_of::<usize>() * 2;

src/lib.rs

@@ -24,12 +24,13 @@ mod rope;
 mod slice;
 
 pub mod traits {
+    //! All traits are re-exported here to allow glob imports.
     pub use {Buf, BufExt, MutBuf, MutBufExt, ByteStr};
 }
 
 const MAX_CAPACITY: usize = u32::MAX as usize;
 
-/// A trait for values that provide random and sequential access to bytes.
+/// A trait for values that provide sequential read access to bytes.
 pub trait Buf {
 
     /// Returns the number of bytes that can be accessed from the Buf
@@ -99,6 +100,7 @@ pub trait Buf {
     }
 }
 
+/// An extension trait providing extra functions applicable to all `Buf` values.
 pub trait BufExt {
 
     /// Read bytes from this Buf into the given sink and advance the cursor by
@@ -106,7 +108,7 @@ pub trait BufExt {
     fn read<S: Sink>(&mut self, dst: S) -> Result<usize, S::Error>;
 }
 
-// TODO: Remove Sized
+/// A trait for values that provide sequential write access to bytes.
 pub trait MutBuf : Sized {
 
     /// Returns the number of bytes that can be accessed from the Buf
@@ -180,6 +182,7 @@ pub trait MutBuf : Sized {
     }
 }
 
+/// An extension trait providing extra functions applicable to all `MutBuf` values.
 pub trait MutBufExt {
 
     /// Write bytes from the given source into the current `MutBuf` and advance
@@ -193,6 +196,9 @@ pub trait MutBufExt {
  *
  */
 
+/// An immutable sequence of bytes. Operations will not mutate the original
+/// value. Since only immutable access is permitted, operations do not require
+/// copying (though, sometimes copying will happen as an optimization).
 pub trait ByteStr : Clone + Sized + Send + Sync + ops::Index<usize, Output=u8> {
 
     // Until HKT lands, the buf must be bound by 'static
@@ -274,13 +280,14 @@ impl<B: MutBuf> MutBufExt for B {
  *
  */
 
-/// An value that reads bytes from a Buf into itself
+/// A value that reads bytes from a Buf into itself
 pub trait Sink {
     type Error;
 
     fn sink<B: Buf>(self, buf: &mut B) -> Result<usize, Self::Error>;
 }
 
+/// A value that writes bytes from itself into a `MutBuf`.
 pub trait Source {
     type Error;
 
@@ -389,7 +396,7 @@ impl Buf for Box<Buf+'static> {
 
 /*
  *
- * ===== BufError / BufResult =====
+ * ===== BufError  =====
  *
  */
 
@@ -398,5 +405,3 @@ pub enum BufError {
     Underflow,
     Overflow,
 }
-
-pub type BufResult<T> = Result<T, BufError>;