WIP: docs(fs): add some documentation

.woodpecker.yml

@@ -2,7 +2,7 @@ steps:
   update-builder-image:
     when:
       - event: cron
-    image: docker.io/woodpeckerci/plugin-docker-buildx:4.2
+    image: docker.io/woodpeckerci/plugin-docker-buildx:5.0
     settings:
       username: kemitix
       repo: git.kemitix.net/kemitix/kxio-builder
@@ -53,7 +53,7 @@ steps:
   publish_to_crates_io:
     when:
       - event: tag
-    image: docker.io/rust:1.81
+    image: docker.io/rust:1.82
     commands:
       - cargo login "$CARGO_REGISTRY_TOKEN"
       - cargo publish --registry crates-io --no-verify

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>;
 }

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)
 }