Addition of doc comments for seek & stream

Author: Majored

src/read/seek.rs

@@ -1,7 +1,7 @@
 // Copyright (c) 2021 Harry [Majored] [hello@majored.pw]
 // MIT License (https://github.com/Majored/rs-async-zip/blob/main/LICENSE)
 
-//! A module for reading ZIP file from a seekable source.
+//! A module for reading ZIP files from a seekable source.
 //!
 //! # Example
 //! ```no_run
@@ -43,7 +43,7 @@ pub struct ZipFileReader<R: AsyncRead + AsyncSeek + Unpin> {
 }
 
 impl<R: AsyncRead + AsyncSeek + Unpin> ZipFileReader<R> {
-    /// Constructs a new ZIP file reader from a mutable reference to a reader.
+    /// Constructs a new ZIP file reader from a reader which implements [`AsyncRead`] and [`AsyncSeek`].
     pub async fn new(mut reader: R) -> Result<ZipFileReader<R>> {
         let (entries, comment) = read_cd(&mut reader).await?;
         Ok(ZipFileReader { reader, entries, comment })
@@ -95,6 +95,10 @@ pub(crate) async fn read_cd<R: AsyncRead + AsyncSeek + Unpin>(
     let delimiter = crate::spec::signature::END_OF_CENTRAL_DIRECTORY.to_le_bytes();
     let mut reader = AsyncDelimiterReader::new(reader, &delimiter);
 
+    // We need to find the last EOCDH as there's a possibility that an inner ZIP file exists with the Stored
+    // compression method, so matching that would be undesirable. For the moment, we match all EOCDHs
+    // sequentially and store the latest's offest.
+    // TODO: Seeking in reverse may be a better a approach for this - needs some testing.
     'outer: loop {
         'inner: loop {
             let mut buffer = [0; async_io_utilities::SUGGESTED_BUFFER_SIZE];

src/read/stream.rs

@@ -1,10 +1,33 @@
 // Copyright (c) 2021 Harry [Majored] [hello@majored.pw]
 // MIT License (https://github.com/Majored/rs-async-zip/blob/main/LICENSE)
 
-//! A module for reading ZIP file from a non-seekable source.
+//! A module for reading ZIP files from a non-seekable source.
+//! 
+//! ## Note
+//! This method fully relies on the information provided in each individual local file header. As a result, this method
+//! doesn't support entries which desynchronise the information provided in the local file header VS the central
+//! directory file header. This is a practice that the 
+//! [specification suggests](https://github.com/Majored/rs-async-zip/blob/main/SPECIFICATION.md#719) when you wish to
+//! conceal that information.
+//! 
+//! ## Example
+//! ```no_run
+//! # use async_zip::read::stream::ZipFileReader;
+//! # use tokio::fs::File;
+//! # use async_zip::error::ZipError;
+//! #
+//! # async fn run() -> Result<(), ZipError> {
+//! let mut file = File::open("./Archive.zip").await?;
+//! let mut zip = ZipFileReader::new(&mut file);
 //!
-//! # Example
-//! ```
+//! // Consume all entries in order.
+//! while !zip.finished() {
+//!     if let Some(reader) = zip.entry_reader().await? {
+//!         reader.read_to_string_crc().await?;
+//!     }
+//! }
+//! #   Ok(())
+//! # }
 //! ```
 
 use crate::error::{Result, ZipError};
@@ -23,21 +46,27 @@ pub struct ZipFileReader<R: AsyncRead + Unpin> {
 }
 
 impl<R: AsyncRead + Unpin> ZipFileReader<R> {
-    /// Constructs a new ZIP file reader from a mutable reference to a reader.
+    /// Constructs a new ZIP file reader from a reader which implements [`AsyncRead`].
     pub fn new(reader: R) -> Self {
         let reader = AsyncPrependReader::new(reader);
         ZipFileReader { reader, entry: None, finished: false }
     }
 
-    /// Returns whether or not `entry_reader()` will yield more entries.
+    /// Returns whether or not it's possible for this reader to yeild more entries.
+    /// 
+    /// # Note
+    /// It's still possible for this function to return false whilst a call to [`ZipFileReader::entry_reader()`]
+    /// returns no entry. This happens in the case where the last entry has been read but the central directory has not
+    /// been reached (and would be reached in a succeeding call to [`ZipFileReader::entry_reader()`]).
     pub fn finished(&self) -> bool {
         self.finished
     }
 
-    /// Opens the next entry for reading if the central directory hasn't already been reached.
+    /// Opens the next entry for reading if the central directory hasn't yet been reached.
+    /// 
+    /// # Note
+    /// It's essential that each entry reader returned by this function is fully consumed before a new one is opened.
     pub async fn entry_reader(&mut self) -> Result<Option<ZipEntryReader<'_, R>>> {
-        // TODO: Ensure the previous entry has been fully read.
-
         if self.finished {
             return Ok(None);
         } else if let Some(inner) = read_lfh(&mut self.reader).await? {