From a902bce55da4309bbca0f7f0ac71e6ff05128fc9 Mon Sep 17 00:00:00 2001
From: EdJoPaTo
 <rfc-conform-git-commit-email@funny-long-domain-label-everyone-hates-as-it-is-too-long.edjopato.de>
Date: Sun, 6 Nov 2022 13:36:30 +0100
Subject: [PATCH] docs: use doc comments and doc tests

---
 src/flatten.rs    |  1 +
 src/identifier.rs | 49 +++++++++++++++++++++++------------------------
 src/lib.rs        | 46 ++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 71 insertions(+), 25 deletions(-)

diff --git a/src/flatten.rs b/src/flatten.rs
index a3ac5f6..132a84d 100644
--- a/src/flatten.rs
+++ b/src/flatten.rs
@@ -14,6 +14,7 @@ impl<'a> Flattened<'a> {
     }
 }
 
+/// Get a flat list of all visible [`TreeItem`s](TreeItem)
 pub fn flatten<'a>(opened: &[TreeIdentifierVec], items: &'a [TreeItem<'a>]) -> Vec<Flattened<'a>> {
     internal(opened, items, &[])
 }
diff --git a/src/identifier.rs b/src/identifier.rs
index bdc5a11..619fd67 100644
--- a/src/identifier.rs
+++ b/src/identifier.rs
@@ -1,35 +1,34 @@
 #![allow(clippy::module_name_repetitions)]
 
+/// Reference to a [`TreeItem`](crate::TreeItem) in a [`Tree`](crate::Tree)
 pub type TreeIdentifier<'a> = &'a [usize];
+/// Reference to a [`TreeItem`](crate::TreeItem) in a [`Tree`](crate::Tree)
 pub type TreeIdentifierVec = Vec<usize>;
 
-pub fn get_without_leaf(identifier: &[usize]) -> (&[usize], Option<&usize>) {
+/// Split a [`TreeIdentifier`] into its branch and leaf
+///
+/// # Examples
+///
+/// ```
+/// # use tui_tree_widget::get_identifier_without_leaf;
+/// let (branch, leaf) = get_identifier_without_leaf(&[2, 4, 6]);
+/// assert_eq!(branch, [2, 4]);
+/// assert_eq!(leaf, Some(&6));
+///
+/// let (branch, leaf) = get_identifier_without_leaf(&[2]);
+/// assert_eq!(branch, []);
+/// assert_eq!(leaf, Some(&2));
+///
+/// let (branch, leaf) = get_identifier_without_leaf(&[]);
+/// assert_eq!(branch, []);
+/// assert_eq!(leaf, None);
+/// ```
+pub fn get_without_leaf(identifier: TreeIdentifier) -> (TreeIdentifier, Option<&usize>) {
     let length = identifier.len();
     let length_without_leaf = length.saturating_sub(1);
 
-    let head = &identifier[0..length_without_leaf];
-    let tail = identifier.get(length_without_leaf);
+    let branch = &identifier[0..length_without_leaf];
+    let leaf = identifier.get(length_without_leaf);
 
-    (head, tail)
-}
-
-#[test]
-fn get_without_leaf_empty() {
-    let (head, tail) = get_without_leaf(&[]);
-    assert_eq!(head.len(), 0);
-    assert_eq!(tail, None);
-}
-
-#[test]
-fn get_without_leaf_single() {
-    let (head, tail) = get_without_leaf(&[2]);
-    assert_eq!(head.len(), 0);
-    assert_eq!(tail, Some(&2));
-}
-
-#[test]
-fn get_without_leaf_multiple() {
-    let (head, tail) = get_without_leaf(&[2, 4, 6]);
-    assert_eq!(head, [2, 4]);
-    assert_eq!(tail, Some(&6));
+    (branch, leaf)
 }
diff --git a/src/lib.rs b/src/lib.rs
index 2d753c9..0adbfb5 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -17,6 +17,14 @@ pub use crate::identifier::{
     get_without_leaf as get_identifier_without_leaf, TreeIdentifier, TreeIdentifierVec,
 };
 
+/// Keeps the state of what is currently selected and what was opened in a [`Tree`]
+///
+/// # Example
+///
+/// ```
+/// # use tui_tree_widget::TreeState;
+/// let mut state = TreeState::default();
+/// ```
 #[derive(Debug, Default, Clone)]
 pub struct TreeState {
     offset: usize,
@@ -149,6 +157,17 @@ impl TreeState {
     }
 }
 
+/// One item inside a [`Tree`]
+///
+/// Can zero or more `children`.
+///
+/// # Example
+///
+/// ```
+/// # use tui_tree_widget::TreeItem;
+/// let a = TreeItem::new_leaf("leaf");
+/// let b = TreeItem::new("root", vec![a]);
+/// ```
 #[derive(Debug, Clone)]
 pub struct TreeItem<'a> {
     text: Text<'a>,
@@ -207,6 +226,33 @@ impl<'a> TreeItem<'a> {
     }
 }
 
+/// A `Tree` which can be rendered
+///
+/// # Example
+///
+/// ```
+/// # use tui_tree_widget::{Tree, TreeItem, TreeState};
+/// # use tui::backend::TestBackend;
+/// # use tui::Terminal;
+/// # use tui::widgets::{Block, Borders};
+/// # fn main() -> std::io::Result<()> {
+/// #     let mut terminal = Terminal::new(TestBackend::new(32, 32)).unwrap();
+/// let mut state = TreeState::default();
+///
+/// let item = TreeItem::new_leaf("leaf");
+/// let items = vec![item];
+///
+/// terminal.draw(|f| {
+///     let area = f.size();
+///
+///     let tree_widget = Tree::new(items.clone())
+///         .block(Block::default().borders(Borders::ALL).title("Tree Widget"));
+///
+///     f.render_stateful_widget(tree_widget, area, &mut state);
+/// })?;
+/// #     Ok(())
+/// # }
+/// ```
 #[derive(Debug, Clone)]
 pub struct Tree<'a> {
     block: Option<Block<'a>>,