Add minimal library documentation

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,

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,27 +85,32 @@ 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)
  .num_threads(self.threads)
  }
 }
 
+/// 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,
 }

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 {