fill docstring...

src/core.rs

@@ -5,26 +5,36 @@ pub mod text;
 pub mod text_editor;
 pub mod tree;
 
+/// Defines a `Len` trait for obtaining the length of a collection and checking if it is empty.
 pub trait Len {
+    /// Returns the length of the collection.
     fn len(&self) -> usize;
+
+    /// Returns `true` if the collection is empty, otherwise `false`.
     fn is_empty(&self) -> bool;
 }
 
+/// Implements the `Len` trait for `Vec<T>`.
 impl<T> Len for Vec<T> {
+    /// Returns the number of elements in the vector.
     fn len(&self) -> usize {
         self.len()
     }
 
+    /// Checks if the vector is empty.
     fn is_empty(&self) -> bool {
         self.is_empty()
     }
 }
 
+/// Implements the `Len` trait for `String`.
 impl Len for String {
+    /// Returns the length of the string.
     fn len(&self) -> usize {
         self.len()
     }
 
+    /// Checks if the string is empty.
     fn is_empty(&self) -> bool {
         self.is_empty()
     }

src/core/checkbox.rs

@@ -5,13 +5,17 @@ use crate::core::listbox::Listbox;
 mod render;
 pub use render::Renderer;
 
+/// A `Checkbox` struct that encapsulates a listbox for item selection and a set of picked (selected) indices.
+/// It allows for multiple selections, toggling the selection state of items, and navigating through the items.
 #[derive(Clone)]
 pub struct Checkbox {
     listbox: Listbox,
     picked: HashSet<usize>,
 }
 
 impl<T: fmt::Display> FromIterator<T> for Checkbox {
+    /// Creates a `Checkbox` from an iterator of items that implement the `Display` trait.
+    /// Each item is added to the listbox, and the set of picked indices is initialized as empty.
     fn from_iter<I: IntoIterator<Item = T>>(iter: I) -> Self {
         Self {
             listbox: Listbox::from_iter(iter),
@@ -21,18 +25,22 @@ impl<T: fmt::Display> FromIterator<T> for Checkbox {
 }
 
 impl Checkbox {
+    /// Returns a reference to the vector of items in the listbox.
     pub fn items(&self) -> &Vec<String> {
         self.listbox.items()
     }
 
+    /// Returns the current position of the cursor within the listbox.
     pub fn position(&self) -> usize {
         self.listbox.position()
     }
 
+    /// Returns a reference to the set of picked (selected) indices.
     pub fn picked_indexes(&self) -> &HashSet<usize> {
         &self.picked
     }
 
+    /// Retrieves the items at the picked (selected) indices as a vector of strings.
     pub fn get(&self) -> Vec<String> {
         self.picked
             .iter()
@@ -42,6 +50,7 @@ impl Checkbox {
             })
     }
 
+    /// Toggles the selection state of the item at the current cursor position within the listbox.
     pub fn toggle(&mut self) {
         if self.picked.contains(&self.listbox.position()) {
             self.picked.remove(&self.listbox.position());
@@ -50,14 +59,19 @@ impl Checkbox {
         }
     }
 
+    /// Moves the cursor backward in the listbox, if possible.
+    /// Returns `true` if the cursor was successfully moved backward, `false` otherwise.
     pub fn backward(&mut self) -> bool {
         self.listbox.backward()
     }
 
+    /// Moves the cursor forward in the listbox, if possible.
+    /// Returns `true` if the cursor was successfully moved forward, `false` otherwise.
     pub fn forward(&mut self) -> bool {
         self.listbox.forward()
     }
 
+    /// Moves the cursor to the head (beginning) of the listbox.
     pub fn move_to_head(&mut self) {
         self.listbox.move_to_head()
     }

src/core/checkbox/render.rs

@@ -12,21 +12,25 @@ use crate::{
 
 use super::Checkbox;
 
+/// Represents a renderer for the `Checkbox` component, capable of visualizing checkboxes in a pane.
+/// It supports custom symbols for the cursor and checkmark, styles for active and inactive items,
+/// and a configurable number of lines for rendering. It also handles key events for navigation and toggling checkboxes.
 #[derive(Clone)]
 pub struct Renderer {
+    /// The `Checkbox` component to be rendered.
     pub checkbox: Checkbox,
 
-    /// Symbol for selected line.
+    /// Symbol for the selected line.
     pub cursor: String,
-    /// Checkmark (within [ ] parentheses).
+    /// Checkmark symbol (displayed within square brackets).
     pub mark: char,
 
-    /// Style for selected line.
+    /// Style for the selected line.
     pub active_item_style: ContentStyle,
-    /// Style for un-selected line.
+    /// Style for unselected lines.
     pub inactive_item_style: ContentStyle,
 
-    /// Num of lines for rendering.
+    /// Number of lines available for rendering.
     pub lines: Option<usize>,
 }
 

src/core/cursor.rs

@@ -1,35 +1,44 @@
 use crate::core::Len;
 
+/// A generic cursor structure for navigating and manipulating collections.
+/// It maintains a position within the collection and provides methods to move forward, backward,
+/// to the head, and to the tail of the collection. It requires the collection to implement the `Len` trait.
 #[derive(Clone)]
 pub struct Cursor<C> {
     contents: C,
     position: usize,
 }
 
 impl<C: Len> Cursor<C> {
+    /// Constructs a new `Cursor` with the given contents, initially positioned at the start.
     pub fn new(contents: C) -> Self {
         Self {
             contents,
             position: 0,
         }
     }
 
+    /// Constructs a new `Cursor` with the given contents and an initial position.
     pub fn new_with_position(contents: C, position: usize) -> Self {
         Self { contents, position }
     }
 
+    /// Returns a reference to the contents.
     pub fn contents(&self) -> &C {
         &self.contents
     }
 
+    /// Returns a mutable reference to the contents.
     pub fn contents_mut(&mut self) -> &mut C {
         &mut self.contents
     }
 
+    /// Returns the current position of the cursor.
     pub fn position(&self) -> usize {
         self.position
     }
 
+    /// Moves the cursor one position backward, if possible. Returns `true` if successful.
     pub fn backward(&mut self) -> bool {
         if 0 < self.position {
             self.position -= 1;
@@ -38,6 +47,7 @@ impl<C: Len> Cursor<C> {
         false
     }
 
+    /// Moves the cursor one position forward, if possible. Returns `true` if successful.
     pub fn forward(&mut self) -> bool {
         let l = self.contents.len();
         if l != 0 && self.position < l - 1 {
@@ -47,14 +57,17 @@ impl<C: Len> Cursor<C> {
         false
     }
 
+    /// Moves the cursor to the head (start) of the contents.
     pub fn move_to_head(&mut self) {
         self.position = 0
     }
 
+    /// Checks if the cursor is at the head (start) of the contents.
     pub fn is_head(&self) -> bool {
         self.position == 0
     }
 
+    /// Moves the cursor to the tail (end) of the contents.
     pub fn move_to_tail(&mut self) {
         let l = self.contents.len();
         if l == 0 {
@@ -64,6 +77,7 @@ impl<C: Len> Cursor<C> {
         }
     }
 
+    /// Checks if the cursor is at the tail (end) of the contents.
     pub fn is_tail(&self) -> bool {
         self.position == self.contents.len() - 1
     }

src/core/listbox.rs

@@ -5,10 +5,15 @@ use crate::core::cursor::Cursor;
 mod render;
 pub use render::Renderer;
 
+/// A `Listbox` struct that encapsulates a list of strings, allowing for navigation and manipulation
+/// through a cursor. It supports basic operations such as moving the cursor forward and backward,
+/// retrieving the current item, and initializing from an iterator of displayable items.
 #[derive(Clone)]
 pub struct Listbox(Cursor<Vec<String>>);
 
 impl<T: fmt::Display> FromIterator<T> for Listbox {
+    /// Creates a `Listbox` from an iterator of items that implement the `Display` trait.
+    /// Each item is converted to a `String` and collected into a `Vec<String>`.
     fn from_iter<I: IntoIterator<Item = T>>(iter: I) -> Self {
         Self(Cursor::new(
             iter.into_iter().map(|e| format!("{}", e)).collect(),
@@ -17,29 +22,38 @@ impl<T: fmt::Display> FromIterator<T> for Listbox {
 }
 
 impl Listbox {
+    /// Returns a reference to the vector of items in the listbox.
     pub fn items(&self) -> &Vec<String> {
         self.0.contents()
     }
 
+    /// Returns the current position of the cursor within the listbox.
     pub fn position(&self) -> usize {
         self.0.position()
     }
 
+    /// Retrieves the item at the current cursor position as a `String`.
+    /// If the cursor is at a position without an item, returns an empty `String`.
     pub fn get(&self) -> String {
         self.items()
             .get(self.position())
             .unwrap_or(&String::new())
             .to_string()
     }
 
+    /// Moves the cursor backward in the listbox, if possible.
+    /// Returns `true` if the cursor was successfully moved backward, `false` otherwise.
     pub fn backward(&mut self) -> bool {
         self.0.backward()
     }
 
+    /// Moves the cursor forward in the listbox, if possible.
+    /// Returns `true` if the cursor was successfully moved forward, `false` otherwise.
     pub fn forward(&mut self) -> bool {
         self.0.forward()
     }
 
+    /// Moves the cursor to the head (beginning) of the listbox.
     pub fn move_to_head(&mut self) {
         self.0.move_to_head()
     }

src/core/listbox/render.rs

@@ -12,19 +12,23 @@ use crate::{
 
 use super::Listbox;
 
+/// Represents a renderer for the `Listbox` component, capable of visualizing a list of items in a pane.
+/// It supports a custom symbol for the selected line, styles for active and inactive items,
+/// and a configurable number of lines for rendering.
 #[derive(Clone)]
 pub struct Renderer {
+    /// The `Listbox` component to be rendered.
     pub listbox: Listbox,
 
-    /// Symbol for selected line.
+    /// Symbol for the selected line.
     pub cursor: String,
 
-    /// Style for selected line.
+    /// Style for the selected line.
     pub active_item_style: ContentStyle,
-    /// Style for un-selected line.
+    /// Style for un-selected lines.
     pub inactive_item_style: ContentStyle,
 
-    /// Num of lines for rendering.
+    /// Number of lines available for rendering.
     pub lines: Option<usize>,
 }
 

src/core/text_editor.rs

@@ -9,6 +9,8 @@ pub use suggest::Suggest;
 mod mode;
 pub use mode::Mode;
 
+/// A text editor that supports basic editing operations such as insert, delete, and overwrite.
+/// It utilizes a cursor to navigate and manipulate the text.
 #[derive(Clone)]
 pub struct TextEditor(Cursor<String>);
 
@@ -22,19 +24,24 @@ impl Default for TextEditor {
 }
 
 impl TextEditor {
+    /// Returns the current text including the cursor.
     pub fn text(&self) -> String {
         self.0.contents().clone()
     }
 
+    /// Returns the text without the cursor.
     pub fn text_without_cursor(&self) -> String {
         let mut ret = self.text();
         ret.pop();
         ret
     }
 
+    /// Returns the current position of the cursor within the text.
     pub fn position(&self) -> usize {
         self.0.position()
     }
+
+    /// Masks all characters except the cursor with the specified mask character.
     pub fn masking(&self, mask: char) -> String {
         self.text()
             .chars()
@@ -43,19 +50,22 @@ impl TextEditor {
             .collect::<String>()
     }
 
+    /// Replaces the current text with new text and positions the cursor at the end.
     pub fn replace(&mut self, new: &str) {
         let mut buf = new.to_owned();
         buf.push(' ');
         let pos = buf.len() - 1;
         *self = Self(Cursor::new_with_position(buf, pos));
     }
 
+    /// Inserts a character at the current cursor position.
     pub fn insert(&mut self, ch: char) {
         let pos = self.position();
         self.0.contents_mut().insert(pos, ch);
         self.forward();
     }
 
+    /// Overwrites the character at the current cursor position with the specified character.
     pub fn overwrite(&mut self, ch: char) {
         if self.0.is_tail() {
             self.insert(ch)
@@ -68,6 +78,7 @@ impl TextEditor {
         }
     }
 
+    /// Erases the character before the cursor position.
     pub fn erase(&mut self) {
         if !self.0.is_head() {
             self.backward();
@@ -76,22 +87,27 @@ impl TextEditor {
         }
     }
 
+    /// Clears all text and resets the editor to its default state.
     pub fn erase_all(&mut self) {
         *self = Self::default();
     }
 
+    /// Moves the cursor to the beginning of the text.
     pub fn move_to_head(&mut self) {
         self.0.move_to_head()
     }
 
+    /// Moves the cursor to the end of the text.
     pub fn move_to_tail(&mut self) {
         self.0.move_to_tail()
     }
 
+    /// Moves the cursor one position backward, if possible.
     pub fn backward(&mut self) -> bool {
         self.0.backward()
     }
 
+    /// Moves the cursor one position forward, if possible.
     pub fn forward(&mut self) -> bool {
         self.0.forward()
     }