From 5056957df7146e5c533700fde0b3112147003230 Mon Sep 17 00:00:00 2001
From: Paul Campbell <pcampbell@kemitix.net>
Date: Mon, 29 Apr 2024 07:25:31 +0100
Subject: [PATCH] docs(fs): add some documentation

---
 src/fs/like.rs | 76 ++++++++++++++++++++++++++++++++++++++++++++++++++
 src/fs/mod.rs  | 20 ++++++++++++-
 2 files changed, 95 insertions(+), 1 deletion(-)

diff --git a/src/fs/like.rs b/src/fs/like.rs
index 19ae0d9..c01b4ea 100644
--- a/src/fs/like.rs
+++ b/src/fs/like.rs
@@ -4,20 +4,96 @@ use super::Result;
 
 use std::path::{Path, PathBuf};
 
+/// A handle for accessing the filesystem.
 pub trait FileSystemLike {
+    /// Returns the base directory for the filesystem that this handle can access.
+    ///
+    /// Many methods expect a [Path] paremeter. This [Path] must be within the base directory of the
+    /// handle. Call [FileSystemLike::base] to get this.
+    ///
+    /// To construct a [Path] within the filesystem:
+    ///
+    /// ```no_run
+    /// let fs = kxio::fs::new(std::env::current_dir()?);
+    /// let file_name = fs.base().join("foo");
+    /// ```
     fn base(&self) -> &Path;
 
+    /// Creates a directory at the path. The parent directory must already exists, if it doesn't
+    /// consider using [FileSystemLike::dir_create_all] instead.
+    ///
+    /// ```no_run
+    /// let fs = kxio::fs::temp()?;
+    /// let dir_name = fs.base().join("subdir");
+    /// fs.dir_create(&dir_name)?;
+    /// ```
     fn dir_create(&self, path: &Path) -> Result<()>;
+
+    /// Creates a directory and any missing parents as the path.
+    ///
+    /// ```no_run
+    /// let fs = kxio::fs::temp()?;
+    /// let path_name = fs.base().join("subdir").join("child");
+    /// fs.dir_create_all(&path_name)?;
+    /// ```
     fn dir_create_all(&self, path: &Path) -> Result<()>;
 
     /// Reads the items in a directory and returns them as an iterator.
     fn dir_read(&self, path: &Path) -> Result<Box<dyn Iterator<Item = Result<DirItem>>>>;
 
+    /// Reads a file into a [String]. Will attempt to read the whole file into memory in one go.
+    ///
+    /// ```no_run
+    /// let fs = kxio::fs::new(std::env::current_dir()?);
+    /// let file_name = fs.base().join("existing_file.txt");
+    /// let file_contents = fs.file_read_to_string(&file_name)?;
+    /// ```
     fn file_read_to_string(&self, path: &Path) -> Result<String>;
+
+    /// Writes a string slice to a file.
+    ///
+    /// ```no_run
+    /// let fs = kxio::fs::temp()?;
+    /// let file_name = fs.base().join("new_file");
+    /// let contents = "contents of new file";
+    /// fs.file_write(&file_name, contents)?;
+    /// ```
     fn file_write(&self, path: &Path, contents: &str) -> Result<()>;
 
+    /// Checks that the path exists.
+    ///
+    /// ```no_run
+    /// let fs = kxio::fs::new(std::env::current_dir()?);
+    /// let path = fs.base().join("foo");
+    /// let exists: bool = fs.path_exists(&path)?;
+    /// ```
     fn path_exists(&self, path: &Path) -> Result<bool>;
+
+    /// Checks whether the path is a directory.
+    ///
+    /// ```no_run
+    /// let fs = kxio::fs::new(std::env::current_dir()?);
+    /// let path = fs.base().join("foo");
+    /// let is_dir: bool = fs.path_is_dir(&path)?;
+    /// ```
     fn path_is_dir(&self, path: &Path) -> Result<bool>;
+
+    /// Checks whether the path is a file.
+    ///
+    /// ```no_run
+    /// let fs = kxio::fs::new(std::env::current_dir()?);
+    /// let path = fs.base().join("foo");
+    /// let is_file: bool = fs.path_is_file(&path)?;
+    /// ```
     fn path_is_file(&self, path: &Path) -> Result<bool>;
+
+    /// Creates a new [PathBuf] within the filesystem.
+    ///
+    /// ```no_run
+    /// let fs = kxio::fs::temp()?;
+    /// let path_of = fs.path_of("subdir/file.txt")?;
+    /// let path = fs.base().join("subdir").join("file.txt");
+    /// assert_eq!(path_of, path);
+    /// ```
     fn path_of(&self, path: PathBuf) -> Result<PathBuf>;
 }
diff --git a/src/fs/mod.rs b/src/fs/mod.rs
index e2b369b..b86b188 100644
--- a/src/fs/mod.rs
+++ b/src/fs/mod.rs
@@ -4,7 +4,7 @@ use derive_more::From;
 
 use crate::fs::like::FileSystemLike;
 
-mod like;
+pub mod like;
 mod real;
 mod temp;
 
@@ -31,10 +31,28 @@ impl std::error::Error for Error {}
 
 pub type Result<T> = core::result::Result<T, Error>;
 
+/// Creates a new handle for accessing the filesystem.
+///
+/// The base parameter is the root directory that all operations must be within.
 pub const fn new(base: PathBuf) -> FileSystem {
     FileSystem::Real(real::new(base))
 }
 
+/// Creates a new handle for accessing a temporary directory on the filesystem.
+///
+/// When this handle is dropped, the temporary directory is deleted.
+///
+/// Calling base on the handle will return the temporary directory.
+///
+/// # Example
+///
+/// This will create a temporary directory and create a file inside it called 'foo':
+///
+/// ```no_run
+/// let fs = kxio::fs::temp()?;
+/// let file_name = fs.base().join("foo");
+/// fs.file_write(&file_name, "contents")?;
+/// ```
 pub fn temp() -> Result<FileSystem> {
     temp::new().map(FileSystem::Temp)
 }