Merge pull request #48 from KSXGitHub/documentation

Improve documentation

Author: KSXGitHub

src/data_tree.rs

@@ -7,6 +7,20 @@ pub use Reflection as DataTreeReflection;
 use super::size::Size;
 
 /// Disk usage data of a filesystem tree.
+///
+/// **Construction:** There are 3 main ways to create a `DataTree`:
+/// * Use [`FsTreeBuilder`](crate::fs_tree_builder::FsTreeBuilder) to create it from the real
+/// filesystem.
+/// * Use [`TreeBuilder`](crate::tree_builder::TreeBuilder) to create it from a representation
+/// of a filesystem.
+/// * Use [`Reflection`].
+///
+/// **Visualization:** Use the [`Visualizer`](crate::visualizer::Visualizer) struct to create an
+/// ASCII chart that visualizes `DataTree`.
+///
+/// **Serialization and deserialization:** _(feature: `json`)_ `DataTree` does not implement
+/// `Serialize` and `Deserialize` traits directly, instead, it can be converted into/from a
+/// [`Reflection`] which implements these traits.
 #[derive(Debug, PartialEq, Eq)]
 pub struct DataTree<Name, Data: Size> {
     name: Name,

src/data_tree/reflection.rs

@@ -24,7 +24,9 @@ use serde::{Deserialize, Serialize};
 /// * To safely convert a `Reflection` into a valid `DataTree`,
 ///   use [`par_try_into_tree`](Self::par_try_into_tree).
 ///
-/// **Serialization and deserialization:** Requires enabling the `json` feature to enable `serde`.
+/// **Serialization and deserialization:** _(feature: `json`)_ `Reflection` implements
+/// `Serialize` and `Deserialize` traits, this allows functions in `serde_json` to convert
+/// a `Reflection` into/from JSON.
 #[derive(Debug, Clone, PartialEq, Eq)]
 #[cfg_attr(feature = "json", derive(Deserialize, Serialize))]
 #[cfg_attr(feature = "json", serde(rename_all = "kebab-case"))]

src/fs_tree_builder.rs

@@ -12,6 +12,25 @@ use std::{
 };
 
 /// Build a [`DataTree`] from a directory tree using [`From`] or [`Into`].
+///
+/// **Example:**
+///
+/// ```no_run
+/// # use parallel_disk_usage::fs_tree_builder::FsTreeBuilder;
+/// use parallel_disk_usage::{
+///     data_tree::DataTree,
+///     os_string_display::OsStringDisplay,
+///     reporter::{ErrorOnlyReporter, ErrorReport},
+///     size::Bytes,
+///     size_getters::GET_APPARENT_SIZE,
+/// };
+/// let builder = FsTreeBuilder {
+///     root: std::env::current_dir().unwrap(),
+///     get_data: GET_APPARENT_SIZE,
+///     reporter: ErrorOnlyReporter::new(ErrorReport::SILENT),
+/// };
+/// let data_tree: DataTree<OsStringDisplay, Bytes> = builder.into();
+/// ```
 #[derive(Debug)]
 pub struct FsTreeBuilder<Data, GetData, Report>
 where
@@ -34,6 +53,7 @@ where
     GetData: Fn(&Metadata) -> Data + Sync,
     Report: Reporter<Data> + Sync,
 {
+    /// Create a [`DataTree`] from an [`FsTreeBuilder`].
     fn from(builder: FsTreeBuilder<Data, GetData, Report>) -> Self {
         let FsTreeBuilder {
             root,

src/tree_builder.rs

@@ -34,6 +34,7 @@ where
     GetInfo: Fn(&Path) -> Info<Name, Data> + Copy + Send + Sync,
     JoinPath: Fn(&Path, &Name) -> Path + Copy + Send + Sync,
 {
+    /// Create a [`DataTree`] from a [`TreeBuilder`].
     fn from(builder: TreeBuilder<Path, Name, Data, GetInfo, JoinPath>) -> Self {
         let TreeBuilder {
             path,

src/visualizer.rs

@@ -16,6 +16,30 @@ use super::{data_tree::DataTree, size::Size};
 use std::{fmt::Display, num::NonZeroUsize};
 
 /// Visualize a [`DataTree`].
+///
+/// The fields of the struct are the construction parameters of the ASCII chart.
+/// The [`Display`] trait can be used to create the ASCII chart.
+///
+/// **Example:**
+///
+/// ```no_run
+/// # use parallel_disk_usage::data_tree::DataTree;
+/// # use parallel_disk_usage::os_string_display::OsStringDisplay;
+/// # use parallel_disk_usage::size::Bytes;
+/// # use parallel_disk_usage::bytes_format::BytesFormat;
+/// # use parallel_disk_usage::visualizer::{Visualizer, Direction, ColumnWidthDistribution};
+/// # fn _wrapper(create_data_tree: fn() -> DataTree<OsStringDisplay, Bytes>) {
+/// let data_tree: DataTree<OsStringDisplay, Bytes> = create_data_tree();
+/// let visualizer = Visualizer {
+///     data_tree: &data_tree,
+///     bytes_format: BytesFormat::MetricUnits,
+///     direction: Direction::BottomUp,
+///     column_width_distribution: ColumnWidthDistribution::total(100),
+///     max_depth: std::num::NonZeroUsize::new(10).unwrap(),
+/// };
+/// println!("{}", visualizer);
+/// # }
+/// ```
 #[derive(Debug)]
 pub struct Visualizer<'a, Name, Data>
 where

src/visualizer/display.rs

@@ -7,6 +7,7 @@ where
     Name: Display,
     Data: Size + Into<u64>,
 {
+    /// Create the ASCII chart.
     fn fmt(&self, formatter: &mut Formatter<'_>) -> Result<(), Error> {
         let write = |line: &String| writeln!(formatter, "{}", line);
         match self.direction {