documentation

24 files changed, 69 insertions, 59 deletions

diff --git a/README.md b/README.md
index 3ba3bee..a29710a 100644
--- a/README.md
+++ b/README.md
@@ -9,7 +9,7 @@ An interactive tree view, a fuzzy search, a balanced BFS descent and customizabl
 
 ### Get an overview of a directory, even a big one:
 
-![overview](doc/20181215-overview.png)
+![overview](img/20181215-overview.png)
 
 Notice the "unlisted" ? That's what makes it usable where the old `tree` command would produce pages of output.
 
@@ -17,7 +17,7 @@ Notice the "unlisted" ? That's what makes it usable where the old `tree` command
 
 ### Find a directory then `cd` to it:
 
-![cd](doc/20181218-cd.png)
+![cd](img/20181218-cd.png)
 
 You can this way navigate to a directory with the minimum amount of keystrokes, even if you don't exactly remember where it is.
 
@@ -34,19 +34,19 @@ Most useful keys for this:
 
 ### See what takes space:
 
-![size](doc/20181215-only-folders-with-size.png)
+![size](img/20181215-only-folders-with-size.png)
 
 To toggle size display, you usually hit `:s`. Sizes are computed in the background, you don't have to wait for them when you navigate.
 
 ### Never lose track of file hierarchy while you fuzzy search:
 
-![size](doc/20181215-search.png)
+![size](img/20181215-search.png)
 
 broot tries to select the most relevant file. You can still go from one match to another one using `<tab>` or arrow keys.
 
 ### Apply a personal shorcut to a file:
 
-![size](doc/20181215-edit.png)
+![size](img/20181215-edit.png)
 
 Just find the file you want to edit with a few keystrokes, type `:e`, then `<enter>` (you should define your prefered editor, see [documentation](documentation.md#verbs)).
 
diff --git a/documentation.md b/documentation.md
index e9f3813..912a9ea 100644
--- a/documentation.md
+++ b/documentation.md
@@ -7,7 +7,7 @@ A broot command is typed in the input at the bottom and is made of two parts, a
 
 Example:
 
-![command](doc/20190110-pattern_verb.png)
+![command](img/20190110-pattern_verb.png)
 
 There the pattern is `car` and the verb shortcut is `e`.
 
@@ -29,7 +29,7 @@ Hitting `?` brings you to the help screen.
 
 Flags are displayed at the bottom right, showing the settings regarding hidden files and .gitignore rules.
 
-![flags](doc/20190101-flags.png)
+![flags](img/20190101-flags.png)
 
 ## Verbs
 
@@ -102,7 +102,7 @@ In the default configuration, it's mapped to `f`.
 
 This setting is displayed at the top right of the screen:
 
-![flags](doc/20190110-flags.png)
+![flags](img/20190110-flags.png)
 
 In the default configuration, it's mapped to `gi`.
 
diff --git a/doc/20181215-edit.png b/img/20181215-edit.png
index 6a7b0ee..6a7b0ee 100644
--- a/doc/20181215-edit.png
+++ b/img/20181215-edit.png
diff --git a/doc/20181215-only-folders-with-size.png b/img/20181215-only-folders-with-size.png
index 41adb6c..41adb6c 100644
--- a/doc/20181215-only-folders-with-size.png
+++ b/img/20181215-only-folders-with-size.png
diff --git a/doc/20181215-overview.png b/img/20181215-overview.png
index d154f3f..d154f3f 100644
--- a/doc/20181215-overview.png
+++ b/img/20181215-overview.png
diff --git a/doc/20181215-search.png b/img/20181215-search.png
index 988dbfb..988dbfb 100644
--- a/doc/20181215-search.png
+++ b/img/20181215-search.png
diff --git a/doc/20181218-cd.png b/img/20181218-cd.png
index 493b842..493b842 100644
--- a/doc/20181218-cd.png
+++ b/img/20181218-cd.png
diff --git a/doc/20190101-flags.png b/img/20190101-flags.png
index ad194fb..ad194fb 100644
--- a/doc/20190101-flags.png
+++ b/img/20190101-flags.png
diff --git a/doc/20190110-flags.png b/img/20190110-flags.png
index 74eb5fc..74eb5fc 100644
--- a/doc/20190110-flags.png
+++ b/img/20190110-flags.png
diff --git a/doc/20190110-pattern_verb.png b/img/20190110-pattern_verb.png
index df0b07d..df0b07d 100644
--- a/doc/20190110-pattern_verb.png
+++ b/img/20190110-pattern_verb.png
diff --git a/src/app.rs b/src/app.rs
index 59c8cb1..ef2ef0f 100644
--- a/src/app.rs
+++ b/src/app.rs
@@ -1,12 +1,12 @@
-/// broot's app is mainly a stack of AppState.
-/// Commands parsed from the input are submitted to the current
-/// appstate, which replies with a stateCmdResult which may
-/// be
-/// - a transition to a new state
-/// - a pop to get back to the previous one
-/// - an operation which keeps the state
-/// - a request to quit broot
-/// - a request to launch an executable (thus leaving broot)
+//! broot's app is mainly a stack of AppState.
+//! Commands parsed from the input are submitted to the current
+//! appstate, which replies with a stateCmdResult which may
+//! be
+//! - a transition to a new state
+//! - a pop to get back to the previous one
+//! - an operation which keeps the state
+//! - a request to quit broot
+//! - a request to launch an executable (thus leaving broot)
 use std::io::{self, stdin, Write};
 use std::sync::atomic::{AtomicUsize, Ordering};
 use std::sync::{mpsc, Arc};
@@ -23,6 +23,7 @@ use crate::spinner::Spinner;
 use crate::status::Status;
 use crate::task_sync::TaskLifetime;
 
+/// Result of applying a command to a state
 pub enum AppStateCmdResult {
     Quit,
     Keep,
@@ -83,6 +84,7 @@ impl App {
         }
     }
 
+    /// This is the main loop of the application
     pub fn run(mut self, con: &AppContext) -> io::Result<Option<Launchable>> {
         let (w, h) = termion::terminal_size()?;
         let mut screen = Screen::new(w, h)?;
@@ -118,8 +120,7 @@ impl App {
         });
         let mut cmd = Command::new();
         screen.write_input(&cmd)?;
-        screen
-            .write_status_text("Hit <esc> to quit, '?' for help, or type some letters to search")?;
+        screen.write_status_text("Hit <esc> to quit, '?' for help, or type some letters to search")?;
         self.state().write_flags(&mut screen, con)?;
         let mut quit = false;
         loop {
diff --git a/src/app_context.rs b/src/app_context.rs
index 3fed960..dcc4f7c 100644
--- a/src/app_context.rs
+++ b/src/app_context.rs
@@ -4,5 +4,5 @@ use crate::verbs::VerbStore;
 /// the configuration things
 pub struct AppContext {
     pub verb_store: VerbStore,
-    pub output_path: Option<String>,
+    pub output_path: Option<String>, // where to write the outputted path (if required with --out)
 }
diff --git a/src/browser_states.rs b/src/browser_states.rs
index 004a6d4..9dc5222 100644
--- a/src/browser_states.rs
+++ b/src/browser_states.rs
@@ -1,4 +1,5 @@
-//! an application state dedicated to displaying a tree
+//! An application state dedicated to displaying a tree.
+//! It's the first and main screen of broot.
 
 use std::io::{self, Write};
 use std::path::PathBuf;
@@ -160,6 +161,8 @@ impl AppState for BrowserState {
         false
     }
 
+    /// do some work, totally or partially, if there's some to do.
+    /// Stop as soon as the lifetime is expired.
     fn do_pending_task(&mut self, tl: &TaskLifetime) {
         if let Some(pat) = &mut self.pending_pattern {
             let start = Instant::now();
diff --git a/src/commands.rs b/src/commands.rs
index d3af72d..38167c9 100644
--- a/src/commands.rs
+++ b/src/commands.rs
@@ -1,10 +1,10 @@
+//! A command is the parsed representation of what the user types
+//!  in the input. It's independant of the state of the application
+//!  (verbs arent checked at this point)
+
 use regex::Regex;
 use termion::event::Key;
 
-/// A command is the parsed representation of what the user types
-///  in the input. It's independant of the state of the application
-///  (verbs arent checked at this point)
-
 #[derive(Debug)]
 pub struct Command {
     pub raw: String,         // what's visible in the input
diff --git a/src/conf.rs b/src/conf.rs
index 3b9970c..bb746d6 100644
--- a/src/conf.rs
+++ b/src/conf.rs
@@ -1,11 +1,12 @@
+//! manage reading the verb shortcuts from the configuration file,
+//! initializing if if it doesn't yet exist
+
 use std::fs;
 use std::io;
 use std::path::{Path, PathBuf};
 use std::result::Result;
 use toml::{self, Value};
 
-/// manage reading the verb shortcuts from the configuration file,
-/// initializing if if it doesn't yet exist
 use custom_error::custom_error;
 use directories::ProjectDirs;
 
@@ -15,7 +16,7 @@ custom_error! {pub ConfError
     MissingField{txt: String}       = "missing field in conf",
 }
 
-// what's needed to handle a verb
+/// what's needed to handle a verb
 #[derive(Debug)]
 pub struct VerbConf {
     pub name: String,
@@ -23,6 +24,7 @@ pub struct VerbConf {
     pub execution: String,
 }
 
+
 #[derive(Debug)]
 pub struct Conf {
     pub verbs: Vec<VerbConf>,
diff --git a/src/external.rs b/src/external.rs
index 26bf349..fb0e8fe 100644
--- a/src/external.rs
+++ b/src/external.rs
@@ -2,8 +2,9 @@ use std::io;
 use std::path::PathBuf;
 use std::process::Command;
 
-// description of a possible launch of an external program
-// (might be more complex, and a sequence of things to try, in the future)
+/// description of a possible launch of an external program
+/// (might be more complex, and a sequence of things to try, in the future).
+/// A launchable can only be executed on end of life of broot.
 #[derive(Debug)]
 pub struct Launchable {
     exe: String,
diff --git a/src/file_sizes.rs b/src/file_sizes.rs
index e3dd92c..2d3f777 100644
--- a/src/file_sizes.rs
+++ b/src/file_sizes.rs
@@ -1,8 +1,8 @@
-// compute the summed size of directories
-// A cache is used to avoid recomputing the
-//  same directories again and again.
-// Hard links are checked to avoid counting
-//  twice an inode.
+/// compute the summed size of directories.
+/// A cache is used to avoid recomputing the
+///  same directories again and again.
+/// Hard links are checked to avoid counting
+///  twice an inode.
 use crate::task_sync::TaskLifetime;
 use std::collections::{HashMap, HashSet};
 use std::fs;
@@ -25,6 +25,9 @@ impl Size {
         })
     }
 
+    /// Return the size of the directory, either by computing it of by
+    ///  fetching it from cache.
+    /// If the lifetime expires before complete computation, None is returned.
     pub fn from_dir(path: &Path, tl: &TaskLifetime) -> Option<Size> {
         lazy_static! {
             static ref size_cache_mutex: Mutex<HashMap<PathBuf, Size>> = Mutex::new(HashMap::new());
diff --git a/src/flat_tree.rs b/src/flat_tree.rs
index 1875429..0b04eeb 100644
--- a/src/flat_tree.rs
+++ b/src/flat_tree.rs
@@ -1,5 +1,5 @@
-//! in the flat_tree structure, every "node" is just a line, there's
-//!  no link from a child to its parent or from a parent to its children.
+/// In the flat_tree structure, every "node" is just a line, there's
+///  no link from a child to its parent or from a parent to its children.
 
 use std::cmp::{self, Ordering};
 use std::path::PathBuf;
@@ -15,14 +15,15 @@ pub enum LineType {
     Dir,
     SymLinkToDir(String),  //
     SymLinkToFile(String), // (to file or to symlink)
-    Pruning,
+    Pruning,               // a "xxx unlisted" line
 }
 
+/// a line in the representation of the file hierarchy
 #[derive(Debug)]
 pub struct TreeLine {
-    pub left_branchs: Box<[bool]>,
+    pub left_branchs: Box<[bool]>, // a depth-sized array telling whether a branch pass
     pub depth: u16,
-    pub name: String, // name of the first unlisted, in case of Pruning
+    pub name: String,    // name of the first unlisted, in case of Pruning
     pub path: PathBuf,
     pub line_type: LineType,
     pub has_error: bool,
@@ -39,7 +40,7 @@ pub struct Tree {
     pub lines: Box<[TreeLine]>,
     pub selection: usize, // there's always a selection (starts with root, which is 0)
     pub options: TreeOptions,
-    pub scroll: i32,        // FIXME usize
+    pub scroll: i32,        // the number of lines at the top hidden because of scrolling
     pub nb_gitignored: u32, // number of times a gitignore pattern excluded a file
 }
 
diff --git a/src/git_ignore.rs b/src/git_ignore.rs
index 33aa4c8..4c975c0 100644
--- a/src/git_ignore.rs
+++ b/src/git_ignore.rs
@@ -1,14 +1,14 @@
-// implements parsing and applying .gitignore files
-// Also manages a stack of such files, because more than one
-// can apply for a dir (i.e when entering a directory we
-// may add a gitignore file to the stack
+//! Implements parsing and applying .gitignore files.
+//! Also manages a stack of such files, because more than one
+//!  can apply for a dir (i.e when entering a directory we
+//!  may add a gitignore file to the stack)
 use glob;
 use regex::Regex;
 use std::fs::File;
 use std::io::{BufRead, BufReader, Result};
 use std::path::{Path, PathBuf};
 
-// a simple rule of a gitignore file
+/// a simple rule of a gitignore file
 #[derive(Clone)]
 struct GitIgnoreRule {
     ok: bool,        // does this rule when matched means the file is good? (usually false)
@@ -62,7 +62,7 @@ impl GitIgnoreRule {
     }
 }
 
-// the rules of a gitignore file
+/// The rules of a gitignore file
 #[derive(Clone)]
 pub struct GitIgnoreFile {
     rules: Vec<GitIgnoreRule>,
@@ -89,9 +89,9 @@ impl GitIgnoreFile {
     }
 }
 
-// a stack of the gitignore files applying to a directory
+/// A stack of the gitignore files applying to a directory.
 pub struct GitIgnoreFilter {
-    pub files: Vec<GitIgnoreFile>,
+    pub files: Vec<GitIgnoreFile>, // the last one is the deepest one
 }
 impl GitIgnoreFilter {
     pub fn applicable_to(path: &Path) -> GitIgnoreFilter {
@@ -139,7 +139,7 @@ impl GitIgnoreFilter {
     }
 }
 
-// an iterator to find all applicable git_ignore files
+/// an iterator to find all applicable git_ignore files
 pub struct GitIgnoreFilesFinder<'a> {
     dir: &'a Path,
 }
diff --git a/src/help_states.rs b/src/help_states.rs
index 7994db3..d44fd71 100644
--- a/src/help_states.rs
+++ b/src/help_states.rs
@@ -46,7 +46,7 @@ impl AppState for HelpState {
     }
 
     fn do_pending_task(&mut self, _tl: &TaskLifetime) {
-        // can't happen
+        unreachable!();
     }
 
     fn display(&mut self, screen: &mut Screen, con: &AppContext) -> io::Result<()> {
diff --git a/src/main.rs b/src/main.rs
index 4e9f5d4..14ff5fe 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -47,6 +47,7 @@ use crate::verbs::VerbStore;
 
 const VERSION: &str = "0.4.6";
 
+// declare the possible CLI arguments, and gets the values
 fn get_cli_args<'a>() -> clap::ArgMatches<'a> {
     clap::App::new("broot")
         .version(VERSION)
@@ -115,6 +116,8 @@ fn configure_log() {
     }
 }
 
+// run the application, and maybe return a launchable
+// which must be run after broot
 fn run() -> Result<Option<Launchable>, ProgramError> {
     configure_log();
 
@@ -167,7 +170,7 @@ fn run() -> Result<Option<Launchable>, ProgramError> {
                 app.push(Box::new(bs));
                 app.run(&con)?
             }
-            _ => None, // should not happen
+            _ => None, // should not happen, as the lifetime is "unlimited"
         },
     )
 }
@@ -176,8 +179,6 @@ fn main() {
     if let Some(launchable) = run().unwrap() {
         info!("launching {:?}", &launchable);
         if let Err(e) = launchable.execute() {
-            println!("Failed to launch {:?}", &launchable);
-            println!("Error: {:?}", e);
             warn!("Failed to launch {:?}", &launchable);
             warn!("Error: {:?}", e);
         }
diff --git a/src/screens.rs b/src/screens.rs
index eed22d8..0138eb2 100644
--- a/src/screens.rs
+++ b/src/screens.rs
@@ -1,5 +1,4 @@
 use std::io::{self, stdout, Write};
-
 use termion::color;
 use termion::raw::{IntoRawMode, RawTerminal};
 use termion::screen::AlternateScreen;
diff --git a/src/task_sync.rs b/src/task_sync.rs
index e4f0333..1380da2 100644
--- a/src/task_sync.rs
+++ b/src/task_sync.rs
@@ -1,9 +1,9 @@
 use std::sync::atomic::{AtomicUsize, Ordering};
 use std::sync::Arc;
 
-// a TL initialized from an Arc<AtomicUsize> stays
-//  alive as long as the passed arc doesn't change.
-// When it changes, is_expired returns true
+/// a TL initialized from an Arc<AtomicUsize> stays
+///  alive as long as the passed arc doesn't change.
+/// When it changes, is_expired returns true
 pub struct TaskLifetime {
     initial_value: usize,
     external_value: Arc<AtomicUsize>,
diff --git a/src/tree_build.rs b/src/tree_build.rs
index 5fbd3ab..08227bb 100644
--- a/src/tree_build.rs
+++ b/src/tree_build.rs
@@ -474,7 +474,6 @@ impl TreeBuilder {
                 lines.push(self.blines[*idx].to_tree_line());
             }
         }
-
         let mut tree = Tree {
             lines: lines.into_boxed_slice(),
             selection: 0,