Merge pull request #265 from zip-rs/explainer

Picking the low-hanging documentation fruit

src/lib.rs

@@ -1,7 +1,26 @@
-//! An ergonomic API for reading and writing ZIP files.
+//! A library for reading and writing ZIP archives.
+//! ZIP is a format designed for cross-platform file "archiving".
+//! That is, storing a collection of files in a single datastream
+//! to make them easier to share between computers.
+//! Additionally, ZIP is able to compress and encrypt files in its
+//! archives.
 //!
 //! The current implementation is based on [PKWARE's APPNOTE.TXT v6.3.9](https://pkware.cachefly.net/webdocs/casestudies/APPNOTE.TXT)
-// TODO(#184): Decide on the crate's bias: Do we prioritise permissiveness/correctness/speed/ergonomics?
+//!
+//! ---
+//!
+//! [`zip`](`crate`) has support for the most common ZIP archives found in common use.
+//! However, in special cases,
+//! there are some zip archives that are difficult to read or write.
+//!
+//! This is a list of supported features:
+//!
+//! |         | Reading | Writing |
+//! | ------- | ------  | ------- |
+//! | Deflate | ✅ [->](`crate::ZipArchive::by_name`)      | ✅ [->](`crate::write::FileOptions::compression_method`) |
+//!
+//!
+//!
 
 #![warn(missing_docs)]
 

src/read.rs

@@ -34,41 +34,45 @@ mod ffi {
     pub const S_IFREG: u32 = 0o0100000;
 }
 
-/// Extract immutable data from `ZipArchive` to make it cheap to clone
+// Put the struct declaration in a private module to convince rustdoc to display ZipArchive nicely
-#[derive(Debug)]
+pub(crate) mod zip_archive {
-struct Shared {
+    /// Extract immutable data from `ZipArchive` to make it cheap to clone
-    files: Vec<ZipFileData>,
+    #[derive(Debug)]
-    names_map: HashMap<String, usize>,
+    pub struct Shared {
-    offset: u64,
+        pub(super) files: Vec<super::ZipFileData>,
-    comment: Vec<u8>,
+        pub(super) names_map: super::HashMap<String, usize>,
-}
+        pub(super) offset: u64,
-
+        pub(super) comment: Vec<u8>,
-/// ZIP archive reader
+    }
-///
+
-/// At the moment, this type is cheap to clone if this is the case for the
+    /// ZIP archive reader
-/// reader it uses. However, this is not guaranteed by this crate and it may
+    ///
-/// change in the future.
+    /// At the moment, this type is cheap to clone if this is the case for the
-///
+    /// reader it uses. However, this is not guaranteed by this crate and it may
-/// ```no_run
+    /// change in the future.
-/// use std::io::prelude::*;
+    ///
-/// fn list_zip_contents(reader: impl Read + Seek) -> zip::result::ZipResult<()> {
+    /// ```no_run
-///     let mut zip = zip::ZipArchive::new(reader)?;
+    /// use std::io::prelude::*;
-///
+    /// fn list_zip_contents(reader: impl Read + Seek) -> zip::result::ZipResult<()> {
-///     for i in 0..zip.len() {
+    ///     let mut zip = zip::ZipArchive::new(reader)?;
-///         let mut file = zip.by_index(i)?;
+    ///
-///         println!("Filename: {}", file.name());
+    ///     for i in 0..zip.len() {
-///         std::io::copy(&mut file, &mut std::io::stdout());
+    ///         let mut file = zip.by_index(i)?;
-///     }
+    ///         println!("Filename: {}", file.name());
-///
+    ///         std::io::copy(&mut file, &mut std::io::stdout());
-///     Ok(())
+    ///     }
-/// }
+    ///
-/// ```
+    ///     Ok(())
-#[derive(Clone, Debug)]
+    /// }
-pub struct ZipArchive<R> {
+    /// ```
-    reader: R,
+    #[derive(Clone, Debug)]
-    shared: Arc<Shared>,
+    pub struct ZipArchive<R> {
+        pub(super) reader: R,
+        pub(super) shared: super::Arc<Shared>,
+    }
 }
 
+pub use zip_archive::{Shared, ZipArchive};
 #[allow(clippy::large_enum_variant)]
 enum CryptoReader<'a> {
     Plaintext(io::Take<&'a mut dyn Read>),

src/types.rs

@@ -1,4 +1,6 @@
 //! Types that specify what is contained in a ZIP.
+#[cfg(doc)]
+use {crate::read::ZipFile, crate::write::FileOptions};
 
 use std::sync::atomic;
 
@@ -24,19 +26,23 @@ impl System {
     }
 }
 
-/// A DateTime field to be used for storing timestamps in a zip file
+/// Representation of a moment in time.
 ///
-/// This structure does bounds checking to ensure the date is able to be stored in a zip file.
+/// Zip files use an old format from DOS to store timestamps,
+/// with its own set of peculiarities.
+/// For example, it has a resolution of 2 seconds!
 ///
-/// When constructed manually from a date and time, it will also check if the input is sensible
+/// A [`DateTime`] can be stored directly in a zipfile with [`FileOptions::last_modified_time`],
-/// (e.g. months are from [1, 12]), but when read from a zip some parts may be out of their normal
+/// or read from one with [`ZipFile::last_modified`]
-/// bounds (e.g. month 0, or hour 31).
 ///
 /// # Warning
 ///
-/// Some utilities use alternative timestamps to improve the accuracy of their
+/// Because there is no timezone associated with the [`DateTime`], they should ideally only
-/// ZIPs, but we don't parse them yet. [We're working on this](https://github.com/zip-rs/zip/issues/156#issuecomment-652981904),
+/// be used for user-facing descriptions. This also means [`DateTime::to_time`] returns an
-/// however this API shouldn't be considered complete.
+/// [`OffsetDateTime`] (which is the equivalent of chrono's `NaiveDateTime`).
+///
+/// Modern zip files store more precise timestamps, which are ignored by [`crate::read::ZipArchive`],
+/// so keep in mind that these timestamps are unreliable. [We're working on this](https://github.com/zip-rs/zip/issues/156#issuecomment-652981904).
 #[derive(Debug, Clone, Copy)]
 pub struct DateTime {
     year: u16,
@@ -168,26 +174,46 @@ impl DateTime {
     }
 
     /// Get the month, where 1 = january and 12 = december
+    ///
+    /// # Warning
+    ///
+    /// When read from a zip file, this may not be a reasonable value
     pub fn month(&self) -> u8 {
         self.month
     }
 
     /// Get the day
+    ///
+    /// # Warning
+    ///
+    /// When read from a zip file, this may not be a reasonable value
     pub fn day(&self) -> u8 {
         self.day
     }
 
     /// Get the hour
+    ///
+    /// # Warning
+    ///
+    /// When read from a zip file, this may not be a reasonable value
     pub fn hour(&self) -> u8 {
         self.hour
     }
 
     /// Get the minute
+    ///
+    /// # Warning
+    ///
+    /// When read from a zip file, this may not be a reasonable value
     pub fn minute(&self) -> u8 {
         self.minute
     }
 
     /// Get the second
+    ///
+    /// # Warning
+    ///
+    /// When read from a zip file, this may not be a reasonable value
     pub fn second(&self) -> u8 {
         self.second
     }

src/write.rs

@@ -42,45 +42,49 @@ enum GenericZipWriter<W: Write + io::Seek> {
     #[cfg(feature = "zstd")]
     Zstd(ZstdEncoder<'static, W>),
 }
-
+// Put the struct declaration in a private module to convince rustdoc to display ZipWriter nicely
-/// ZIP archive generator
+pub(crate) mod zip_writer {
-///
+    use super::*;
-/// Handles the bookkeeping involved in building an archive, and provides an
+    /// ZIP archive generator
-/// API to edit its contents.
+    ///
-///
+    /// Handles the bookkeeping involved in building an archive, and provides an
-/// ```
+    /// API to edit its contents.
-/// # fn doit() -> zip::result::ZipResult<()>
+    ///
-/// # {
+    /// ```
-/// # use zip::ZipWriter;
+    /// # fn doit() -> zip::result::ZipResult<()>
-/// use std::io::Write;
+    /// # {
-/// use zip::write::FileOptions;
+    /// # use zip::ZipWriter;
-///
+    /// use std::io::Write;
-/// // We use a buffer here, though you'd normally use a `File`
+    /// use zip::write::FileOptions;
-/// let mut buf = [0; 65536];
+    ///
-/// let mut zip = zip::ZipWriter::new(std::io::Cursor::new(&mut buf[..]));
+    /// // We use a buffer here, though you'd normally use a `File`
-///
+    /// let mut buf = [0; 65536];
-/// let options = zip::write::FileOptions::default().compression_method(zip::CompressionMethod::Stored);
+    /// let mut zip = zip::ZipWriter::new(std::io::Cursor::new(&mut buf[..]));
-/// zip.start_file("hello_world.txt", options)?;
+    ///
-/// zip.write(b"Hello, World!")?;
+    /// let options = zip::write::FileOptions::default().compression_method(zip::CompressionMethod::Stored);
-///
+    /// zip.start_file("hello_world.txt", options)?;
-/// // Apply the changes you've made.
+    /// zip.write(b"Hello, World!")?;
-/// // Dropping the `ZipWriter` will have the same effect, but may silently fail
+    ///
-/// zip.finish()?;
+    /// // Apply the changes you've made.
-///
+    /// // Dropping the `ZipWriter` will have the same effect, but may silently fail
-/// # Ok(())
+    /// zip.finish()?;
-/// # }
+    ///
-/// # doit().unwrap();
+    /// # Ok(())
-/// ```
+    /// # }
-pub struct ZipWriter<W: Write + io::Seek> {
+    /// # doit().unwrap();
-    inner: GenericZipWriter<W>,
+    /// ```
-    files: Vec<ZipFileData>,
+    pub struct ZipWriter<W: Write + io::Seek> {
-    stats: ZipWriterStats,
+        pub(super) inner: GenericZipWriter<W>,
-    writing_to_file: bool,
+        pub(super) files: Vec<ZipFileData>,
-    writing_to_extra_field: bool,
+        pub(super) stats: ZipWriterStats,
-    writing_to_central_extra_field_only: bool,
+        pub(super) writing_to_file: bool,
-    writing_raw: bool,
+        pub(super) writing_to_extra_field: bool,
-    comment: Vec<u8>,
+        pub(super) writing_to_central_extra_field_only: bool,
+        pub(super) writing_raw: bool,
+        pub(super) comment: Vec<u8>,
+    }
 }
+pub use zip_writer::ZipWriter;
 
 #[derive(Default)]
 struct ZipWriterStats {