Add minimal library documentation

3 files changed, 28 insertions, 11 deletions

diff --git a/src/aggregate.rs b/src/aggregate.rs
index 6079e04..5fe5536 100644
--- a/src/aggregate.rs
+++ b/src/aggregate.rs
@@ -3,6 +3,9 @@ use failure::Error;
 use std::borrow::Cow;
 use std::{io, path::Path};
 
+/// Aggregate the given `paths` and write information about them to `out` in a human-readable format.
+/// If `compute_total` is set, it will write an additional line with the total size across all given `paths`.
+/// If `sort_by_size_in_bytes` is set, we will sort all sizes (ascending) before outputting them.
 pub fn aggregate(
     mut out: impl io::Write,
     options: WalkOptions,
diff --git a/src/common.rs b/src/common.rs
index 95b6967..33fddf8 100644
--- a/src/common.rs
+++ b/src/common.rs
@@ -2,30 +2,36 @@ use jwalk::WalkDir;
 use std::fmt;
 use std::path::Path;
 
+/// Specifies a way to format bytes
 pub enum ByteFormat {
+    /// metric format, based on 1000.
     Metric,
+    /// binary format, based on 1024
     Binary,
+    /// raw bytes, without additional formatting
     Bytes,
 }
 
-pub enum Sorting {
+pub(crate) enum Sorting {
     None,
-    Alphabetical,
 }
 
+/// Specify the kind of color to use
 #[derive(Clone, Copy)]
 pub enum Color {
+    /// Use no color
     None,
+    /// Use terminal colors
     Terminal,
 }
 
-pub struct DisplayColor<C> {
+pub(crate) struct DisplayColor<C> {
     kind: Color,
     color: C,
 }
 
 impl Color {
-    pub fn display<C>(&self, color: C) -> DisplayColor<C> {
+    pub(crate) fn display<C>(&self, color: C) -> DisplayColor<C> {
         DisplayColor { kind: *self, color }
     }
 }
@@ -42,17 +48,20 @@ where
     }
 }
 
+/// Configures a filesystem walk, including output and formatting options.
 pub struct WalkOptions {
+    /// The amount of threads to use. Refer to [`WalkDir::num_threads()`](https://docs.rs/jwalk/0.4.0/jwalk/struct.WalkDir.html#method.num_threads)
+    /// for more information.
     pub threads: usize,
-    pub format: ByteFormat,
+    pub byte_format: ByteFormat,
     pub color: Color,
 }
 
 impl WalkOptions {
-    pub fn format_bytes(&self, b: u64) -> String {
+    pub(crate) fn format_bytes(&self, b: u64) -> String {
         use byte_unit::Byte;
         use ByteFormat::*;
-        let binary = match self.format {
+        let binary = match self.byte_format {
             Bytes => return format!("{} b", b),
             Binary => true,
             Metric => false,
@@ -66,7 +75,7 @@ impl WalkOptions {
                 "{:>8} {:>unit_width$}",
                 bytes,
                 unit,
-                unit_width = match self.format {
+                unit_width = match self.byte_format {
                     Binary => 3,
                     Metric => 2,
                     _ => 2,
@@ -76,11 +85,10 @@ impl WalkOptions {
         }
     }
 
-    pub fn iter_from_path(&self, path: &Path, sort: Sorting) -> WalkDir {
+    pub(crate) fn iter_from_path(&self, path: &Path, sort: Sorting) -> WalkDir {
         WalkDir::new(path)
             .preload_metadata(true)
             .sort(match sort {
-                Sorting::Alphabetical => true,
                 Sorting::None => false,
             })
             .skip_hidden(false)
@@ -88,15 +96,21 @@ impl WalkOptions {
     }
 }
 
+/// Statistics obtained during a filesystem walk
 #[derive(Default, Debug)]
 pub struct Statistics {
+    /// The amount of files we have seen
     pub files_traversed: u64,
+    /// The size of the smallest file encountered in bytes
     pub smallest_file_in_bytes: u64,
+    /// The size of the largest file encountered in bytes
     pub largest_file_in_bytes: u64,
 }
 
+/// Information we gather during a filesystem walk
 #[derive(Default)]
 pub struct WalkResult {
+    /// The amount of io::errors we encountered. Can happen when fetching meta-data, or when reading the directory contents.
     pub num_errors: u64,
     pub stats: Statistics,
 }
diff --git a/src/main.rs b/src/main.rs
index a687030..33d108c 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -19,7 +19,7 @@ fn run() -> Result<(), Error> {
     let stdout_locked = stdout.lock();
     let walk_options = dua::WalkOptions {
         threads: opt.threads.unwrap_or(0),
-        format: opt.format.map(Into::into).unwrap_or(ByteFormat::Metric),
+        byte_format: opt.format.map(Into::into).unwrap_or(ByteFormat::Metric),
         color: if atty::is(atty::Stream::Stdout) {
             Color::Terminal
         } else {