Update docs, remove some deprecated methods, and substitute crate version into docstring

src/lib.rs

@@ -46,13 +46,16 @@ mod types;
 pub mod write;
 mod zipcrypto;
 
-/// Unstable APIs
+#[doc = "Unstable APIs\n\
-///
+\
-/// All APIs accessible by importing this module are unstable; They may be changed in patch releases.
+All APIs accessible by importing this module are unstable; They may be changed in patch \
-/// You MUST you an exact version specifier in `Cargo.toml`, to indicate the version of this API you're using:
+releases. You MUST use an exact version specifier in `Cargo.toml`, to indicate the version of this \
-///
+API you're using:\n\
-/// ```toml
+\
-/// [dependencies]
+```toml\n
-/// zip = "=1.1.1"
+[dependencies]\n
-/// ```
+zip = \"="]
+#[doc=env!("CARGO_PKG_VERSION")]
+#[doc = "\"\n\
+```"]
 pub mod unstable;

src/read.rs

@@ -1002,43 +1002,12 @@ impl<'a> ZipFile<'a> {
         &self.data.file_name_raw
     }
 
-    /// Get the name of the file in a sanitized form. It truncates the name to the first NULL byte,
-    /// removes a leading '/' and removes '..' parts.
-    #[deprecated(
-        since = "0.5.7",
-        note = "by stripping `..`s from the path, the meaning of paths can change.
-                `mangled_name` can be used if this behaviour is desirable"
-    )]
-    pub fn sanitized_name(&self) -> PathBuf {
-        self.mangled_name()
-    }
-
-    /// Rewrite the path, ignoring any path components with special meaning.
-    ///
-    /// - Absolute paths are made relative
-    /// - [`ParentDir`]s are ignored
-    /// - Truncates the filename at a NULL byte
-    ///
-    /// This is appropriate if you need to be able to extract *something* from
-    /// any archive, but will easily misrepresent trivial paths like
-    /// `foo/../bar` as `foo/bar` (instead of `bar`). Because of this,
-    /// [`ZipFile::enclosed_name`] is the better option in most scenarios.
-    ///
-    /// [`ParentDir`]: `Component::ParentDir`
-    pub fn mangled_name(&self) -> PathBuf {
-        self.data.file_name_sanitized()
-    }
-
     /// Ensure the file path is safe to use as a [`Path`].
     ///
     /// - It can't contain NULL bytes
     /// - It can't resolve to a path outside the current directory
     ///   > `foo/../bar` is fine, `foo/../../bar` is not.
     /// - It can't be an absolute path
-    ///
-    /// This will read well-formed ZIP files correctly, and is resistant
-    /// to path-based exploits. It is recommended over
-    /// [`ZipFile::mangled_name`].
     pub fn enclosed_name(&self) -> Option<PathBuf> {
         self.data.enclosed_name()
     }

src/read/stream.rs

@@ -153,15 +153,13 @@ impl ZipStreamFileMetadata {
     /// Rewrite the path, ignoring any path components with special meaning.
     ///
     /// - Absolute paths are made relative
-    /// - [`ParentDir`]s are ignored
+    /// - [std::path::Component::ParentDir]s are ignored
     /// - Truncates the filename at a NULL byte
     ///
     /// This is appropriate if you need to be able to extract *something* from
     /// any archive, but will easily misrepresent trivial paths like
     /// `foo/../bar` as `foo/bar` (instead of `bar`). Because of this,
     /// [`ZipFile::enclosed_name`] is the better option in most scenarios.
-    ///
-    /// [`ParentDir`]: `Component::ParentDir`
     pub fn mangled_name(&self) -> PathBuf {
         self.0.file_name_sanitized()
     }
@@ -174,8 +172,7 @@ impl ZipStreamFileMetadata {
     /// - It can't be an absolute path
     ///
     /// This will read well-formed ZIP files correctly, and is resistant
-    /// to path-based exploits. It is recommended over
+    /// to path-based exploits.
-    /// [`ZipFile::mangled_name`].
     pub fn enclosed_name(&self) -> Option<PathBuf> {
         self.0.enclosed_name()
     }

src/write.rs

@@ -507,9 +507,9 @@ impl<A: Read + Write + Seek> ZipWriter<A> {
     /// read previously-written files and not overwrite them.
     ///
     /// Note: when using an `inner` that cannot overwrite flushed bytes, do not wrap it in a
-    /// [std::io::BufWriter], because that has a [seek] method that implicitly calls [flush], and
+    /// [std::io::BufWriter], because that has a [Seek::seek] method that implicitly calls
-    /// ZipWriter needs to seek backward to update each file's header with the size and checksum
+    /// [BufWriter::flush], and ZipWriter needs to seek backward to update each file's header with
-    /// after writing the body.
+    /// the size and checksum after writing the body.
     ///
     /// This setting is false by default.
     pub fn set_flush_on_finish_file(&mut self, flush_on_finish_file: bool) {
@@ -519,7 +519,7 @@ impl<A: Read + Write + Seek> ZipWriter<A> {
 
 impl<A: Read + Write + Seek> ZipWriter<A> {
     /// Adds another copy of a file already in this archive. This will produce a larger but more
-    /// widely-compatible archive compared to [shallow_copy_file]. Does not copy alignment.
+    /// widely-compatible archive compared to [Self::shallow_copy_file]. Does not copy alignment.
     pub fn deep_copy_file(&mut self, src_name: &str, dest_name: &str) -> ZipResult<()> {
         self.finish_file()?;
         let write_position = self.inner.get_plain().stream_position()?;