From f1074bc6a9928eb9be549eef04d25c9411619695 Mon Sep 17 00:00:00 2001
From: Marli Frost <marli@frost.red>
Date: Sun, 23 Jan 2022 21:45:41 +0000
Subject: [PATCH] doc: remove re-exports section from crate root

Making the paths to the types private forces rustdoc to render
the structs inline in the crate root.
This is simpler to see when first reading the API doc
---
 src/read.rs  | 52 ++++++++++++++++++----------------
 src/write.rs | 80 +++++++++++++++++++++++++++-------------------------
 2 files changed, 70 insertions(+), 62 deletions(-)

diff --git a/src/read.rs b/src/read.rs
index a9f173fd..4dff725b 100644
--- a/src/read.rs
+++ b/src/read.rs
@@ -32,31 +32,35 @@ mod ffi {
     pub const S_IFREG: u32 = 0o0100000;
 }
 
-/// ZIP archive reader
-///
-/// ```no_run
-/// use std::io::prelude::*;
-/// fn list_zip_contents(reader: impl Read + Seek) -> zip::result::ZipResult<()> {
-///     let mut zip = zip::ZipArchive::new(reader)?;
-///
-///     for i in 0..zip.len() {
-///         let mut file = zip.by_index(i)?;
-///         println!("Filename: {}", file.name());
-///         std::io::copy(&mut file, &mut std::io::stdout());
-///     }
-///
-///     Ok(())
-/// }
-/// ```
-#[derive(Clone, Debug)]
-pub struct ZipArchive<R> {
-    reader: R,
-    files: Vec<ZipFileData>,
-    names_map: HashMap<String, usize>,
-    offset: u64,
-    comment: Vec<u8>,
-}
+// Put the struct declaration in a private module to convince rustdoc to display ZipArchive nicely
+pub(crate) mod zip_archive {
 
+    /// ZIP archive reader
+    ///
+    /// ```no_run
+    /// use std::io::prelude::*;
+    /// fn list_zip_contents(reader: impl Read + Seek) -> zip::result::ZipResult<()> {
+    ///     let mut zip = zip::ZipArchive::new(reader)?;
+    ///
+    ///     for i in 0..zip.len() {
+    ///         let mut file = zip.by_index(i)?;
+    ///         println!("Filename: {}", file.name());
+    ///         std::io::copy(&mut file, &mut std::io::stdout());
+    ///     }
+    ///
+    ///     Ok(())
+    /// }
+    /// ```
+    #[derive(Clone, Debug)]
+    pub struct ZipArchive<R> {
+        pub(super) reader: R,
+        pub(super) files: Vec<super::ZipFileData>,
+        pub(super) names_map: super::HashMap<String, usize>,
+        pub(super) offset: u64,
+        pub(super) comment: Vec<u8>,
+    }
+}
+pub use zip_archive::ZipArchive;
 enum CryptoReader<'a> {
     Plaintext(io::Take<&'a mut dyn Read>),
     ZipCrypto(ZipCryptoReaderValid<io::Take<&'a mut dyn Read>>),
diff --git a/src/write.rs b/src/write.rs
index 17fd3344..7c9ccdf3 100644
--- a/src/write.rs
+++ b/src/write.rs
@@ -42,45 +42,49 @@ enum GenericZipWriter<W: Write + io::Seek> {
     #[cfg(feature = "zstd")]
     Zstd(ZstdEncoder<'static, W>),
 }
-
-/// ZIP archive generator
-///
-/// Handles the bookkeeping involved in building an archive, and provides an
-/// API to edit its contents.
-///
-/// ```
-/// # fn doit() -> zip::result::ZipResult<()>
-/// # {
-/// # use zip::ZipWriter;
-/// use std::io::Write;
-/// use zip::write::FileOptions;
-///
-/// // We use a buffer here, though you'd normally use a `File`
-/// let mut buf = [0; 65536];
-/// let mut zip = zip::ZipWriter::new(std::io::Cursor::new(&mut buf[..]));
-///
-/// let options = zip::write::FileOptions::default().compression_method(zip::CompressionMethod::Stored);
-/// zip.start_file("hello_world.txt", options)?;
-/// zip.write(b"Hello, World!")?;
-///
-/// // Apply the changes you've made.
-/// // Dropping the `ZipWriter` will have the same effect, but may silently fail
-/// zip.finish()?;
-///
-/// # Ok(())
-/// # }
-/// # doit().unwrap();
-/// ```
-pub struct ZipWriter<W: Write + io::Seek> {
-    inner: GenericZipWriter<W>,
-    files: Vec<ZipFileData>,
-    stats: ZipWriterStats,
-    writing_to_file: bool,
-    writing_to_extra_field: bool,
-    writing_to_central_extra_field_only: bool,
-    writing_raw: bool,
-    comment: Vec<u8>,
+// Put the struct declaration in a private module to convince rustdoc to display ZipWriter nicely
+pub(crate) mod zip_writer {
+    use super::*;
+    /// ZIP archive generator
+    ///
+    /// Handles the bookkeeping involved in building an archive, and provides an
+    /// API to edit its contents.
+    ///
+    /// ```
+    /// # fn doit() -> zip::result::ZipResult<()>
+    /// # {
+    /// # use zip::ZipWriter;
+    /// use std::io::Write;
+    /// use zip::write::FileOptions;
+    ///
+    /// // We use a buffer here, though you'd normally use a `File`
+    /// let mut buf = [0; 65536];
+    /// let mut zip = zip::ZipWriter::new(std::io::Cursor::new(&mut buf[..]));
+    ///
+    /// let options = zip::write::FileOptions::default().compression_method(zip::CompressionMethod::Stored);
+    /// zip.start_file("hello_world.txt", options)?;
+    /// zip.write(b"Hello, World!")?;
+    ///
+    /// // Apply the changes you've made.
+    /// // Dropping the `ZipWriter` will have the same effect, but may silently fail
+    /// zip.finish()?;
+    ///
+    /// # Ok(())
+    /// # }
+    /// # doit().unwrap();
+    /// ```
+    pub struct ZipWriter<W: Write + io::Seek> {
+        pub(super) inner: GenericZipWriter<W>,
+        pub(super) files: Vec<ZipFileData>,
+        pub(super) stats: ZipWriterStats,
+        pub(super) writing_to_file: bool,
+        pub(super) writing_to_extra_field: bool,
+        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 {