From 13c82f79da995140d333034d3ed9a07a454f5f3f Mon Sep 17 00:00:00 2001
From: Nathan Fisher <jeang3nie@hitchhiker-linux.org>
Date: Tue, 4 Jul 2023 20:13:38 -0400
Subject: [PATCH] Add doc comments for many public facing types

---
 src/checksum.rs |  8 ++++++++
 src/file.rs     |  4 ++++
 src/filetype.rs |  9 ++++++++-
 src/node.rs     | 28 +++++++++++++++++++++++++++-
 src/special.rs  |  1 +
 src/stream.rs   |  2 ++
 6 files changed, 50 insertions(+), 2 deletions(-)

diff --git a/src/checksum.rs b/src/checksum.rs
index 8ba684d..5b0d270 100644
--- a/src/checksum.rs
+++ b/src/checksum.rs
@@ -3,11 +3,19 @@ use {
     std::io::{Read, Write},
 };
 
+/// Optional checksumming for individual files
 #[derive(Debug)]
 pub enum Checksum {
+    /// Md5 checksumming, fastest
     Md5([u8; 16]),
+    /// Sha1 checksumming. On par with md5.
     Sha1([u8; 20]),
+    /// The most thorough checksumming offered. Use this if data integrity is of
+    /// utmost importance and computational overhead is of lesser importance.
     Sha256([u8; 32]),
+    /// Do not use checksumming. If this option is selected it is recommended that
+    /// the entire archive is downloaded in entirety and checksummed to ensure it's
+    /// integrity, as was the pattern with Unix 'tar' archives and 'iso' images
     Skip,
 }
 
diff --git a/src/file.rs b/src/file.rs
index 3cbb7f6..6c1dd32 100644
--- a/src/file.rs
+++ b/src/file.rs
@@ -6,10 +6,14 @@ use {
     std::io::{Read, Write},
 };
 
+/// A representation of a regular file as an archive member
 #[derive(Debug)]
 pub struct File {
+    /// The length of this file
     pub len: u64,
+    /// The optional checksum of this file
     pub checksum: Checksum,
+    /// The bytes making up this file
     pub data: Vec<u8>,
 }
 
diff --git a/src/filetype.rs b/src/filetype.rs
index 4270f23..309e709 100644
--- a/src/filetype.rs
+++ b/src/filetype.rs
@@ -3,15 +3,22 @@ use {
     std::io::{Read, Write},
 };
 
-#[repr(u8)]
+/// An enum representing the type of file of an archive member
 #[derive(Debug)]
 pub enum FileType {
+    /// A normal file and it's contained data
     Normal(File),
+    /// A hard link to another file in this archive
     HardLink(String),
+    /// A soft link to another file
     SoftLink(String),
+    /// A directory inode
     Directory,
+    /// A character (buffered) device
     Character(Special),
+    /// A block device
     Block(Special),
+    /// A Unix named pipe (fifo)
     Fifo,
 }
 
diff --git a/src/node.rs b/src/node.rs
index d94974a..767979e 100644
--- a/src/node.rs
+++ b/src/node.rs
@@ -39,17 +39,27 @@ impl From<u32> for Kind {
     }
 }
 
+/// A representation of a file and it's associated metadata.
 #[derive(Debug)]
 pub struct Node {
+    /// The filesystem path to this file
     pub name: String,
+    /// The Unix permissions bits of this file
     pub mode: u32,
+    /// The user id of this file's owner
     pub uid: u32,
+    /// The group id of this file's owner
     pub gid: u32,
+    /// The most recent modification time of this file
     pub mtime: u64,
+    /// The type of file this node represents
     pub filetype: FileType,
 }
 
 impl Node {
+    /// Reads a `Node` from an archive file or stream of Nodes.
+    /// > Note: this function reads an already created node. To create a new node
+    /// > from a file, use the `from_path` method.
     pub fn read<T: Read>(reader: &mut T) -> Result<Self, Error> {
         let mut len = [0; 8];
         reader.read_exact(&mut len)?;
@@ -74,6 +84,10 @@ impl Node {
         })
     }
 
+    /// Write a `Node` struct into it's on-disk archive representation.
+    /// > Note: this function saves the data to the archive format's on-disk
+    /// > representation. To extract the contents of a `Node` and write out the
+    /// > file it represents, use the `extract` method instead.
     pub fn write<T: Write>(&self, writer: &mut T) -> Result<(), Error> {
         let len = self.name.len() as u64;
         writer.write_all(&len.to_le_bytes())?;
@@ -86,10 +100,18 @@ impl Node {
         Ok(())
     }
 
+    /// Creates a new node from a file which exists on the filesystem
+    /// ### Parameters
+    /// - path - the path to this file
+    /// - checksum - a zeroed out `Checksum` variant to be used if the inline
+    ///   checksumming feature is to be used
+    /// - links - this should be passed to each invocation of `from_path` used
+    ///   during the creation of a single archive, to identify hard links and to
+    ///   avoid writing their data out more than once.
     pub fn from_path(
         path: &str,
         checksum: Checksum,
-        links: Mutex<HashMap<u64, String>>,
+        links: &Mutex<HashMap<u64, String>>,
     ) -> Result<Self, Error> {
         let name = String::from(path);
         let fd = fs::File::open(path)?;
@@ -174,4 +196,8 @@ impl Node {
             filetype,
         })
     }
+
+    pub fn extract(&self, prefix: Option<&str>) -> Result<(), Error> {
+        todo!()
+    }
 }
diff --git a/src/special.rs b/src/special.rs
index 7537d40..108ff63 100644
--- a/src/special.rs
+++ b/src/special.rs
@@ -3,6 +3,7 @@ use {
     std::io::{Read, Write},
 };
 
+/// Represents the major and minor numbers of a Unix special Device node
 #[derive(Debug)]
 pub struct Special {
     pub major: u32,
diff --git a/src/stream.rs b/src/stream.rs
index 7345ed3..ce243bc 100644
--- a/src/stream.rs
+++ b/src/stream.rs
@@ -6,6 +6,8 @@ use {
     },
 };
 
+/// An iterator over a series of archive `Node`'s. This struct is generic over any
+/// type which implements `Read`, such as a file or a network stream.
 #[derive(Debug)]
 pub struct Stream<T: Read> {
     reader: T,