From 4543a375e2e3f2ca2c3ff7ada431a867225f1e0f Mon Sep 17 00:00:00 2001
From: Adrian Wannenmacher <tfld@tfld.dev>
Date: Sun, 24 Sep 2023 05:52:27 +0200
Subject: [PATCH] add some documentation

---
 README.md     | 40 ++++++++++++++++++++++++++++++++++++++++
 src/id.rs     |  1 +
 src/main.rs   |  2 ++
 src/name.rs   |  5 +++--
 src/output.rs |  3 +++
 5 files changed, 49 insertions(+), 2 deletions(-)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..024d86e
--- /dev/null
+++ b/README.md
@@ -0,0 +1,40 @@
+# tree-owners
+
+Find all owners (user and group) inside a directory tree.
+
+## Usage
+
+To see available options run: `tree-owners --help`
+
+Basic example when running in this repository:
+```
+$ tree-owners .
+users:
+    adrian
+
+groups:
+    users
+```
+
+Using `uid`s and `gid`s:
+```
+$ tree-owners --raw .
+users:
+    1000
+
+groups:
+    985
+```
+
+Using `json` output:
+```
+$ tree-owners --json .
+{
+  "users": [
+    "adrian"
+  ],
+  "groups": [
+    "users"
+  ]
+}
+```
diff --git a/src/id.rs b/src/id.rs
index 395f3a1..fae728f 100644
--- a/src/id.rs
+++ b/src/id.rs
@@ -2,6 +2,7 @@ use std::{collections::BTreeSet, fmt::Display};
 
 use serde::Serialize;
 
+/// Unique `uid`s and `gid`s.
 #[derive(Debug, Default, Serialize)]
 pub struct Ids {
     pub users: BTreeSet<u32>,
diff --git a/src/main.rs b/src/main.rs
index e012313..0337faf 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -35,6 +35,7 @@ fn main() -> Result<()> {
     Ok(())
 }
 
+/// Command line arguments.
 #[derive(Debug, Parser)]
 #[clap(author, about, version)]
 struct Args {
@@ -50,6 +51,7 @@ struct Args {
     pub roots: Vec<PathBuf>,
 }
 
+/// Perform gid & uid gathering for a file, or a directory and its children.
 fn fs_entry(entry: &Path, summary: &mut Ids) -> Result<()> {
     let display = entry.display();
     ensure!(
diff --git a/src/name.rs b/src/name.rs
index b46709f..04d7405 100644
--- a/src/name.rs
+++ b/src/name.rs
@@ -1,11 +1,12 @@
 use std::{collections::BTreeSet, fmt::Display};
 
-use anyhow::{anyhow,Error, Result};
-use file_owner::{Owner, Group};
+use anyhow::{anyhow, Error, Result};
+use file_owner::{Group, Owner};
 use serde::Serialize;
 
 use crate::id::Ids;
 
+/// Unique user and group names.
 #[derive(Debug, Default, Serialize)]
 pub struct Names {
     pub users: BTreeSet<String>,
diff --git a/src/output.rs b/src/output.rs
index dbe76f0..fdd93ad 100644
--- a/src/output.rs
+++ b/src/output.rs
@@ -1,7 +1,10 @@
 use serde::Serialize;
 
+/// Data that can be printed to the console.
 pub trait Output {
+    /// A human readable representation of the data.
     fn human_readable(&self) -> String;
+    /// A `json` representation of the data.
     fn json(&self) -> Result<String, serde_json::Error>;
 }