Added doc strings

examples/ls.toml

@@ -1,11 +1,20 @@
 watched-command = "ls"
 interval = 3.0
+
+# all lines
 bold = false
+
+# cursor line
 cursor-fg = "black"
 cursor-bg = "blue"
 cursor-bold = true
+
+# selected lines
 selected-bg = "red"
+
+# header lines
 header-lines = 1
+header-fg = "blue"
 
 [keybindings]
 "esc" = [ "unselect-all", "help-hide" ]

src/command.rs

@@ -40,8 +40,8 @@ pub struct Interruptible {
 }
 
 // Advantages of the Type-State Builder Pattern:
-// 1. We don't have any option/enum (an alternative configuration strategy)
-// checking overhead at runtime.
+// 1. We don't have any option/enum checking (an alternative configuration
+// strategy) overhead at runtime.
 // 2. We can guarantee that we handled all possible Command "variants"
 // (combination of config options), that we use, at compile-time.
 // 3. Arguably, this also results in separated, cleaner code.
@@ -50,7 +50,6 @@ pub struct Interruptible {
 /// environment variables, whether the output is captured and whether the
 /// execution can be interrupted. Utilizes the type-state builder pattern to
 /// enforce these configurations at compile-time.
-// #[derive(Clone)]
 pub struct CommandBuilder<B = NonBlocking, E = WithoutEnv, O = NoOutput, I = NonInterruptible> {
     command: String,
     blocking: B,

src/ui/state/lines/line.rs

@@ -15,7 +15,7 @@ pub struct Line {
 }
 
 impl Line {
-    /// Create a new Line with a given style.
+    /// Create a new Line with a given `style`.
     /// The formatted string was formatted according to the user's field
     /// separator.
     /// The unformatted and formatted strings can both contain ANSI escape
@@ -37,7 +37,6 @@ impl Line {
 
     /// Add one space before the line's content to create separation from the
     /// left frame edge.
-    #[inline]
     fn format_line_content(line_content: &str) -> String {
         format!(" {}", line_content)
     }

src/ui/state/lines/mod.rs

@@ -8,8 +8,7 @@ use crate::config::Styles;
 use crate::config::{Fields, TableFormatter};
 use anyhow::Result;
 use derive_more::{From, Into};
-use itertools::izip;
-use itertools::Itertools;
+use itertools::{izip, Itertools};
 use ratatui::{
     prelude::{Backend, Constraint},
     style::Style,
@@ -18,14 +17,26 @@ use ratatui::{
 };
 use std::cmp::max;
 
-// TODO: explain why Line and LineSelection have to be separate
-
+/// The state of the lines, which can be drawn in order to be displayed
+/// in the UI.
 pub struct Lines {
+    /// Stores all output lines from the watched command.
     lines: Vec<Line>,
+    /// Stores which lines are selected. The reason why this is separate
+    /// from `lines` is that the `lines` are updated periodically,
+    /// but the selection of lines stays persistant between `lines`-updates.
+    /// However, the length of the `line_selections` will always be equal to
+    /// that of `lines`, meaning it will be resized on `lines`-updates.
     line_selections: LineSelections,
+    /// The styles used to style the `lines` and `line_selections`.
     styles: Styles,
+    /// Specifies the delimiter and shown fields that should be displayed
+    /// for each line.
     fields: Fields,
+    /// The first index after the header lines, which is the smallest possible
+    /// index the cursor can take.
     index_after_header_lines: usize,
+    /// The line index of the cursor.
     cursor_index: Option<usize>,
     // TODO: deprecate in future
     table_state: TableState,
@@ -58,16 +69,17 @@ impl Lines {
         frame.render_stateful_widget(table, frame.size(), &mut self.table_state);
     }
 
-    // TODO: might be better suited as a new() method or similar
-    pub fn update_lines(&mut self, lines: String) -> Result<()> {
-        let formatted: Vec<Option<String>> = match lines.as_str().format_as_table(&self.fields)? {
-            // All lines have formatting.
-            Some(formatted) => formatted.lines().map(str::to_owned).map(Some).collect(),
-            // No lines have formatting.
-            None => vec![None; lines.lines().count()],
-        };
+    /// Update the lines to `new_lines`.
+    pub fn update_lines(&mut self, new_lines: String) -> Result<()> {
+        let formatted: Vec<Option<String>> =
+            match new_lines.as_str().format_as_table(&self.fields)? {
+                // All lines have formatting.
+                Some(formatted) => formatted.lines().map(str::to_owned).map(Some).collect(),
+                // No lines have formatting.
+                None => vec![None; new_lines.lines().count()],
+            };
 
-        self.lines = izip!(lines.lines(), formatted)
+        self.lines = izip!(new_lines.lines(), formatted)
             .enumerate()
             .map(|(i, (unformatted, formatted))| {
                 let style = if i < self.index_after_header_lines {

src/ui/state/lines/selected_lines/mod.rs

@@ -19,7 +19,7 @@ pub struct LineSelections {
 impl LineSelections {
     /// Get referencing iterator.
     pub fn iter(&self) -> impl Iterator<Item = &LineSelection> {
-        (&self.selections).into_iter()
+        self.selections.iter()
     }
 
     /// Resize the line selections to `new_len`.