Added documentation and moved types to top

src/bin/extract.rs

@@ -6,7 +6,7 @@ fn main()
     let fname = Path::new(args[1].as_slice());
     let file = std::io::File::open(&fname);
 
-    let zipcontainer = zip::reader::ZipReader::new(file).unwrap();
+    let zipcontainer = zip::ZipReader::new(file).unwrap();
 
     for file in zipcontainer.files()
     {

src/bin/write_sample.rs

@@ -11,11 +11,7 @@ fn doit() -> std::io::IoResult<()>
     let fname = Path::new(args[1].as_slice());
     let file = std::io::File::create(&fname).unwrap();
 
-    let mut zip = zip::writer::ZipWriter::new(file);
+    let mut zip = zip::ZipWriter::new(file);
-
-
-//    try!(zip.start_file(b"test", zip::types::Stored));
-//    try!(zip.write(b""));
 
     try!(zip.start_file(b"test/readme.txt", zip::types::Stored));
     try!(zip.write(b"Hello, World!\n"));

src/crc32.rs

@@ -1,3 +1,5 @@
+//! Helper module to compute a CRC32 checksum
+
 use std::io;
 
 static CRC32_TABLE : [u32, ..256] = [
@@ -46,6 +48,7 @@ static CRC32_TABLE : [u32, ..256] = [
 	0xb40bbe37, 0xc30c8ea1, 0x5a05df1b, 0x2d02ef8d
 ];
 
+/// Update the checksum original based upon the contents of buf.
 pub fn crc32(original: u32, buf: &[u8]) -> u32
 {
     let mut crc = original ^ !0u32;
@@ -58,6 +61,7 @@ pub fn crc32(original: u32, buf: &[u8]) -> u32
     return crc ^ !0u32;
 }
 
+/// Reader that validates the CRC32 when it reaches the EOF.
 pub struct Crc32Reader<R>
 {
     inner: R,
@@ -67,6 +71,7 @@ pub struct Crc32Reader<R>
 
 impl<R: Reader> Crc32Reader<R>
 {
+    /// Get a new Crc32Reader which check the inner reader against checksum.
     pub fn new(inner: R, checksum: u32) -> Crc32Reader<R>
     {
         Crc32Reader

src/lib.rs

@@ -1,13 +1,19 @@
+//! A basic ZipReader/Writer crate
+
 #![feature(phase)]
 #![feature(unsafe_destructor)]
+#![warn(missing_doc)]
 
 #[phase(plugin, link)] extern crate log;
 extern crate time;
 extern crate flate2;
 
+pub use reader::ZipReader;
+pub use writer::ZipWriter;
+
 mod util;
 mod spec;
 pub mod crc32;
-pub mod reader;
+mod reader;
 pub mod types;
-pub mod writer;
+mod writer;

src/reader.rs

@@ -7,6 +7,30 @@ use std::io::{IoResult, IoError};
 use std::cell::RefCell;
 use flate2::FlateReader;
 
+/// Wrapper for reading the contents of a ZIP file.
+///
+/// ```
+/// fn doit() -> std::io::IoResult<()>
+/// {
+///     // For demonstration purposes we read from an empty buffer.
+///     // Normally a File object would be used.
+///     let buf = [0u8, 128];
+///     let mut reader = std::io::BufReader::new(&buf);
+///
+///     let zip = try!(zip::ZipReader::new(reader));
+///
+///     for file in zip.files()
+///     {
+///         println!("Filename: {}", file.file_name_string());
+///         let mut file_reader = try!(zip.read_file(file));
+///         let first_byte = try!(file_reader.read_byte());
+///         println!("{}", first_byte);
+///     }
+///     Ok(())
+/// }
+///
+/// println!("Result: {}", doit());
+/// ```
 pub struct ZipReader<T>
 {
     inner: RefCell<T>,
@@ -25,6 +49,7 @@ fn unsupported_zip_error<T>(detail: &str) -> IoResult<T>
 
 impl<T: Reader+Seek> ZipReader<T>
 {
+    /// Opens a ZIP file and parses the content headers.
     pub fn new(mut reader: T) -> IoResult<ZipReader<T>>
     {
         let footer = try!(spec::CentralDirectoryEnd::find_and_parse(&mut reader));
@@ -45,11 +70,18 @@ impl<T: Reader+Seek> ZipReader<T>
         Ok(ZipReader { inner: RefCell::new(reader), files: files })
     }
 
+    /// An iterator over the information of all contained files.
     pub fn files(&self) -> ::std::slice::Items<ZipFile>
     {
         self.files.as_slice().iter()
     }
 
+    /// Gets a reader for a contained zipfile.
+    ///
+    /// Possible errors:
+    ///
+    /// * `ResourceUnavailable`: when another reader returned from this function is still active
+    /// * `OtherIoError`: if the file is encrypted or has an unsupported compression
     pub fn read_file(&self, file: &ZipFile) -> IoResult<Box<Reader>>
     {
         let mut inner_reader = match self.inner.try_borrow_mut()

src/types.rs

@@ -1,49 +1,81 @@
+//! Types that specify what is contained in a ZIP.
+
 use time;
 
+/// Compression methods for the contents of a ZIP file.
 #[deriving(FromPrimitive, Clone)]
 pub enum CompressionMethod
 {
+    /// The file is stored (no compression)
     Stored = 0,
+    /// The file is Shrunk
     Shrunk = 1,
+    /// The file is Reduced with compression factor 1
     Reduced1 = 2,
+    /// The file is Reduced with compression factor 2
     Reduced2 = 3,
+    /// The file is Reduced with compression factor 3
     Reduced3 = 4,
+    /// The file is Reduced with compression factor 4
     Reduced4 = 5,
+    /// The file is Imploded
     Imploded = 6,
+    /// The file is Deflated
     Deflated = 8,
+    /// Enhanced Deflating using Deflate64(tm)
     Deflate64 = 9,
+    /// PKWARE Data Compression Library Imploding (old IBM TERSE)
     PkwareImploding = 10,
+    /// File is compressed using BZIP2 algorithm
     Bzip2 = 12,
+    /// LZMA (EFS)
     LZMA = 14,
+    /// File is compressed using IBM TERSE (new)
     IBMTerse = 18,
+    /// IBM LZ77 z Architecture (PFS)
     LZ77 = 19,
+    /// WavPack compressed data
     WavPack = 97,
+    /// PPMd version I, Rev 1
     PPMdI1 = 98,
+    /// Unknown (invalid) compression
     Unknown = 100000,
 }
 
-
+/// Structure representing a ZIP file.
 pub struct ZipFile
 {
+    /// True if the file is encrypted.
     pub encrypted: bool,
+    /// Compression method used to store the file
     pub compression_method: CompressionMethod,
+    /// Last modified time. This will only have a 2 second precision.
     pub last_modified_time: time::Tm,
+    /// CRC32 checksum
     pub crc32: u32,
+    /// Size of the file in the ZIP
     pub compressed_size: u64,
+    /// Size of the file when extracted
     pub uncompressed_size: u64,
+    /// Name of the file
     pub file_name: Vec<u8>,
+    /// File comment
     pub file_comment: Vec<u8>,
+    /// Specifies where the local header of the file starts
     pub header_start: u64,
+    /// Specifies where the compressed data of the file starts
     pub data_start: u64,
 }
 
 impl ZipFile
 {
+    /// Lossy UTF-8 interpretation of the file name
     pub fn file_name_string(&self) -> String
     {
         String::from_utf8_lossy(self.file_name.as_slice()).into_string()
     }
 
+    /// Lossy UTF-8 interpretation of the file comment
     pub fn file_comment_string(&self) -> String
     {
         String::from_utf8_lossy(self.file_comment.as_slice()).into_string()

src/writer.rs

@@ -17,6 +17,27 @@ enum GenericZipWriter<W>
     Deflater(DeflateEncoder<W>),
 }
 
+/// Generator for ZIP files.
+///
+/// ```
+/// fn doit() -> std::io::IoResult<()>
+/// {
+///     // For this example we write to a buffer, but normally you should use a File
+///     let mut buf = [0u8, ..65536];
+///     let w = std::io::BufWriter::new(&mut buf);
+///     let mut zip = zip::ZipWriter::new(w);
+///
+///     try!(zip.start_file(b"hello_world.txt", zip::types::Stored));
+///     try!(zip.write(b"Hello, World!"));
+///
+///     // Optionally finish the zip. (this is also done on drop)
+///     try!(zip.finalize());
+///
+///     Ok(())
+/// }
+///
+/// println!("Result: {}", doit());
+/// ```
 pub struct ZipWriter<W>
 {
     inner: GenericZipWriter<W>,
@@ -63,6 +84,9 @@ impl ZipWriterStats
 
 impl<W: Writer+Seek> ZipWriter<W>
 {
+    /// Initializes the ZipWriter.
+    ///
+    /// Before writing to this object, the start_file command should be called.
     pub fn new(inner: W) -> ZipWriter<W>
     {
         ZipWriter
@@ -73,6 +97,7 @@ impl<W: Writer+Seek> ZipWriter<W>
         }
     }
 
+    /// Start a new file for with the requested compression method.
     pub fn start_file(&mut self, name: &[u8], compression: types::CompressionMethod) -> IoResult<()>
     {
         try!(self.finish_file());
@@ -126,6 +151,7 @@ impl<W: Writer+Seek> ZipWriter<W>
         Ok(())
     }
 
+    /// Finish the last file and write all other zip-structures
     pub fn finalize(&mut self) -> IoResult<()>
     {
         try!(self.finish_file());