add some documentation

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"
+  ]
+}
+```

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>,

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!(

src/name.rs

@@ -1,11 +1,12 @@
 use std::{collections::BTreeSet, fmt::Display};
 
 use anyhow::{anyhow, Error, Result};
-use file_owner::{Owner, Group};
+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>,

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>;
 }