flate: add documentation

src/libflate/lib.rs

@@ -10,7 +10,11 @@
 
 /*!
 
-Simple compression
+Simple [DEFLATE][def]-based compression. This is a wrapper around the
+[`miniz`][mz] library, which is a one-file pure-C implementation of zlib.
+
+[def]: https://en.wikipedia.org/wiki/DEFLATE
+[mz]: https://code.google.com/p/miniz/
 
 */
 
@@ -31,23 +35,21 @@ extern crate libc;
 use std::c_vec::CVec;
 use libc::{c_void, size_t, c_int};
 
-
-pub mod rustrt {
-    use libc::{c_void, size_t, c_int};
-    #[link(name = "miniz", kind = "static")]
-    extern {
-        pub fn tdefl_compress_mem_to_heap(psrc_buf: *c_void,
-                                          src_buf_len: size_t,
-                                          pout_len: *mut size_t,
-                                          flags: c_int)
-                                          -> *mut c_void;
-
-        pub fn tinfl_decompress_mem_to_heap(psrc_buf: *c_void,
-                                            src_buf_len: size_t,
-                                            pout_len: *mut size_t,
-                                            flags: c_int)
-                                            -> *mut c_void;
-    }
+#[link(name = "miniz", kind = "static")]
+extern {
+    /// Raw miniz compression function.
+    fn tdefl_compress_mem_to_heap(psrc_buf: *c_void,
+                                      src_buf_len: size_t,
+                                      pout_len: *mut size_t,
+                                      flags: c_int)
+                                      -> *mut c_void;
+
+    /// Raw miniz decompression function.
+    fn tinfl_decompress_mem_to_heap(psrc_buf: *c_void,
+                                        src_buf_len: size_t,
+                                        pout_len: *mut size_t,
+                                        flags: c_int)
+                                        -> *mut c_void;
 }
 
 static LZ_NORM : c_int = 0x80;  // LZ with 128 probes, "normal"
@@ -57,7 +59,7 @@ static TDEFL_WRITE_ZLIB_HEADER : c_int = 0x01000; // write zlib header and adler
 fn deflate_bytes_internal(bytes: &[u8], flags: c_int) -> Option<CVec<u8>> {
     unsafe {
         let mut outsz : size_t = 0;
-        let res = rustrt::tdefl_compress_mem_to_heap(bytes.as_ptr() as *c_void,
+        let res = tdefl_compress_mem_to_heap(bytes.as_ptr() as *c_void,
                                                      bytes.len() as size_t,
                                                      &mut outsz,
                                                      flags);
@@ -69,18 +71,20 @@ fn deflate_bytes_internal(bytes: &[u8], flags: c_int) -> Option<CVec<u8>> {
     }
 }
 
+/// Compress a buffer, without writing any sort of header on the output.
 pub fn deflate_bytes(bytes: &[u8]) -> Option<CVec<u8>> {
     deflate_bytes_internal(bytes, LZ_NORM)
 }
 
+/// Compress a buffer, using a header that zlib can understand.
 pub fn deflate_bytes_zlib(bytes: &[u8]) -> Option<CVec<u8>> {
     deflate_bytes_internal(bytes, LZ_NORM | TDEFL_WRITE_ZLIB_HEADER)
 }
 
 fn inflate_bytes_internal(bytes: &[u8], flags: c_int) -> Option<CVec<u8>> {
     unsafe {
         let mut outsz : size_t = 0;
-        let res = rustrt::tinfl_decompress_mem_to_heap(bytes.as_ptr() as *c_void,
+        let res = tinfl_decompress_mem_to_heap(bytes.as_ptr() as *c_void,
                                                        bytes.len() as size_t,
                                                        &mut outsz,
                                                        flags);
@@ -92,10 +96,12 @@ fn inflate_bytes_internal(bytes: &[u8], flags: c_int) -> Option<CVec<u8>> {
     }
 }
 
+/// Decompress a buffer, without parsing any sort of header on the input.
 pub fn inflate_bytes(bytes: &[u8]) -> Option<CVec<u8>> {
     inflate_bytes_internal(bytes, 0)
 }
 
+/// Decompress a buffer that starts with a zlib header.
 pub fn inflate_bytes_zlib(bytes: &[u8]) -> Option<CVec<u8>> {
     inflate_bytes_internal(bytes, TINFL_FLAG_PARSE_ZLIB_HEADER)
 }