From ac86d6267821e770ea8dbe1033d51be89e4f3888 Mon Sep 17 00:00:00 2001
From: Nick Groenen <nick@groenen.me>
Date: Wed, 23 Dec 2020 00:12:16 +0100
Subject: [PATCH] Add brief library documentation to all public types and
 functions

---
 src/lib.rs    | 24 ++++++++++++++++++++++++
 src/walker.rs | 19 +++++++++++++++++++
 2 files changed, 43 insertions(+)

diff --git a/src/lib.rs b/src/lib.rs
index 8654a67..b415dd6 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -31,35 +31,48 @@ const NOTE_RECURSION_LIMIT: usize = 10;
 
 #[non_exhaustive]
 #[derive(Debug, Snafu)]
+/// ExportError represents all errors which may be returned when using this crate.
 pub enum ExportError {
     #[snafu(display("failed to read from '{}'", path.display()))]
+    /// This occurs when a read IO operation fails.
     ReadError {
         path: PathBuf,
         source: std::io::Error,
     },
 
     #[snafu(display("failed to write to '{}'", path.display()))]
+    /// This occurs when a write IO operation fails.
     WriteError {
         path: PathBuf,
         source: std::io::Error,
     },
 
     #[snafu(display("Encountered an error while trying to walk '{}'", path.display()))]
+    /// This occurs when an error is encountered while trying to walk a directory.
     WalkDirError {
         path: PathBuf,
         source: ignore::Error,
     },
 
     #[snafu(display("No such file or directory: {}", path.display()))]
+    /// This occurs when an operation is requested on a file or directory which does not exist.
     PathDoesNotExist { path: PathBuf },
 
     #[snafu(display("Invalid character encoding encountered"))]
+    /// This error may occur when invalid UTF8 is encountered.
+    ///
+    /// Currently, operations which assume UTF8 perform lossy encoding however.
     CharacterEncodingError { source: str::Utf8Error },
 
     #[snafu(display("Recursion limit exceeded"))]
+    /// This error occurs when embedded notes are too deeply nested or cause an infinite loop.
+    ///
+    /// When this happens, `file_tree` contains a list of all the files which were processed
+    /// leading up to this error.
     RecursionLimitExceeded { file_tree: Vec<PathBuf> },
 
     #[snafu(display("Failed to export '{}'", path.display()))]
+    /// This occurs when a file fails to export successfully.
     FileExportError {
         path: PathBuf,
         #[snafu(source(from(ExportError, Box::new)))]
@@ -80,6 +93,12 @@ pub enum FrontmatterStrategy {
 }
 
 #[derive(Debug, Clone)]
+/// Exporter provides the main interface to this library.
+///
+/// Users are expected to create an Exporter using [`Exporter::new`], optionally followed by
+/// customization using [`Exporter::frontmatter_strategy`] and [`Exporter::walk_options`].
+///
+/// After that, calling [`Exporter::run`] will start the export process.
 pub struct Exporter<'a> {
     root: PathBuf,
     destination: PathBuf,
@@ -149,6 +168,8 @@ impl Context {
 }
 
 impl<'a> Exporter<'a> {
+    /// Create a new exporter which reads notes from `source` and exports these to
+    /// `destination`.
     pub fn new(source: PathBuf, destination: PathBuf) -> Exporter<'a> {
         Exporter {
             root: source,
@@ -159,16 +180,19 @@ impl<'a> Exporter<'a> {
         }
     }
 
+    /// Set the [`WalkOptions`] to be used for this exporter.
     pub fn walk_options(&mut self, options: WalkOptions<'a>) -> &mut Exporter<'a> {
         self.walk_options = options;
         self
     }
 
+    /// Set the [`FrontmatterStrategy`] to be used for this exporter.
     pub fn frontmatter_strategy(&mut self, strategy: FrontmatterStrategy) -> &mut Exporter<'a> {
         self.frontmatter_strategy = strategy;
         self
     }
 
+    /// Export notes using the settings configured on this exporter.
     pub fn run(&mut self) -> Result<()> {
         if !self.root.exists() {
             return Err(ExportError::PathDoesNotExist {
diff --git a/src/walker.rs b/src/walker.rs
index efbbae8..c2e9330 100644
--- a/src/walker.rs
+++ b/src/walker.rs
@@ -8,10 +8,26 @@ type Result<T, E = ExportError> = std::result::Result<T, E>;
 type FilterFn = dyn Fn(&DirEntry) -> bool + Send + Sync + 'static;
 
 #[derive(Clone)]
+/// WalkOptions specifies how an Obsidian vault directory is scanned for eligible files to export.
 pub struct WalkOptions<'a> {
+    /// The filename for ignore files, following the
+    /// [gitignore](https://git-scm.com/docs/gitignore) syntax.
+    ///
+    /// By default `.export-ignore` is used.
     pub ignore_filename: &'a str,
+    /// Whether to ignore hidden files.
+    ///
+    /// This is enabled by default.
     pub ignore_hidden: bool,
+    /// Whether to honor git's ignore rules (`.gitignore` files, `.git/config/exclude`, etc) if
+    /// the target is within a git repository.
+    ///
+    /// This is enabled by default.
     pub honor_gitignore: bool,
+    /// An optional custom filter function which is called for each directory entry to determine if
+    /// it should be included or not.
+    ///
+    /// This is passed to [`ignore::WalkBuilder::filter_entry`].
     pub filter_fn: Option<Box<&'static FilterFn>>,
 }
 
@@ -26,6 +42,7 @@ impl<'a> fmt::Debug for WalkOptions<'a> {
 }
 
 impl<'a> WalkOptions<'a> {
+    /// Create a new set of options using default values.
     pub fn new() -> WalkOptions<'a> {
         WalkOptions {
             ignore_filename: ".export-ignore",
@@ -60,6 +77,8 @@ impl<'a> Default for WalkOptions<'a> {
     }
 }
 
+/// `vault_contents` returns all of the files in an Obsidian vault located at `path` which would be
+/// exported when using the given [WalkOptions].
 pub fn vault_contents(path: &Path, opts: WalkOptions) -> Result<Vec<PathBuf>> {
     let mut contents = Vec::new();
     let walker = opts.build_walker(path);