Version 1.0.0v1.0.0

22 files changed, 99 insertions, 49 deletions

diff --git a/CHANGELOG.md b/CHANGELOG.md
index c3bf22e..6d602db 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -1,3 +1,7 @@
+<a name="v1.0.0"></a>
+### v1.0.0 - 2020-09-01
+- nothing new, which is better when you want to call your software stable
+
 <a name="v0.20.3"></a>
 ### v0.20.3 - 2020-08-23
 - fix a few problems with tabulation rendering
diff --git a/Cargo.lock b/Cargo.lock
index 3c88ffa..59f1535 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -76,12 +76,6 @@ checksum = "cdb031dd78e28731d87d56cc8ffef4a8f36ca26c38fe2de700543e627f8a464a"
 
 [[package]]
 name = "base64"
-version = "0.11.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b41b7ea54a0c9d92199de89e20e58d49f02f8e699814ef3fdf266f6f748d15c7"
-
-[[package]]
-name = "base64"
 version = "0.12.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3441f0f7b02788e948e47f457ca01f1d7e6d92c693bc132c22b087d3141c03ff"
@@ -121,7 +115,7 @@ dependencies = [
 
 [[package]]
 name = "broot"
-version = "0.20.3"
+version = "1.0.0"
 dependencies = [
  "ansi_colours",
  "bet",
@@ -180,9 +174,9 @@ checksum = "2e8c087f005730276d1096a652e92a8bacee2e2472bcc9715a74d2bec38b5820"
 
 [[package]]
 name = "bytemuck"
-version = "1.3.1"
+version = "1.4.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "db7a1029718df60331e557c9e83a55523c955e5dd2a7bfeffad6bbd50b538ae9"
+checksum = "92046dbb6f9332943252123f53623e0a6d513651af14967e2991c371ec20201c"
 
 [[package]]
 name = "byteorder"
@@ -510,7 +504,7 @@ checksum = "7abc8dd8451921606d809ba32e95b6111925cd2906060d2dcc29c070220503eb"
 dependencies = [
  "cfg-if",
  "libc",
- "wasi",
+ "wasi 0.9.0+wasi-snapshot-preview1",
 ]
 
 [[package]]
@@ -585,9 +579,9 @@ dependencies = [
 
 [[package]]
 name = "image"
-version = "0.23.8"
+version = "0.23.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "543904170510c1b5fb65140485d84de4a57fddb2ed685481e9020ce3d2c9f64c"
+checksum = "974e194911d1f7efe3cd8a8f9db3b767e43536327e899e8bc9a12ef5711b74d2"
 dependencies = [
  "bytemuck",
  "byteorder",
@@ -704,9 +698,9 @@ dependencies = [
 
 [[package]]
 name = "libz-sys"
-version = "1.1.0"
+version = "1.1.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "af67924b8dd885cccea261866c8ce5b74d239d272e154053ff927dae839f5ae9"
+checksum = "23b34178653005c1181711c333f0e5604a14a1b5115c814fd42304bdd16245e0"
 dependencies = [
  "cc",
  "libc",
@@ -1030,7 +1024,7 @@ version = "1.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7b336d94e8e4ce29bf15bba393164629764744c567e8ad306cc1fdd0119967fd"
 dependencies = [
- "base64 0.12.3",
+ "base64",
  "chrono",
  "indexmap",
  "line-wrap",
@@ -1145,9 +1139,9 @@ dependencies = [
 
 [[package]]
 name = "rayon"
-version = "1.3.1"
+version = "1.4.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "62f02856753d04e03e26929f820d0a0a337ebe71f849801eea335d464b349080"
+checksum = "cfd016f0c045ad38b5251be2c9c0ab806917f82da4d36b2a327e5166adad9270"
 dependencies = [
  "autocfg",
  "crossbeam-deque",
@@ -1157,12 +1151,12 @@ dependencies = [
 
 [[package]]
 name = "rayon-core"
-version = "1.7.1"
+version = "1.8.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e92e15d89083484e11353891f1af602cc661426deb9564c298b270c726973280"
+checksum = "91739a34c4355b5434ce54c9086c5895604a9c278586d1f1aa95e04f66b525a0"
 dependencies = [
+ "crossbeam-channel",
  "crossbeam-deque",
- "crossbeam-queue",
  "crossbeam-utils",
  "lazy_static",
  "num_cpus",
@@ -1176,9 +1170,9 @@ checksum = "41cc0f7e4d5d4544e8861606a285bb08d3e70712ccc7d2b84d7c0ccfaf4b05ce"
 
 [[package]]
 name = "redox_users"
-version = "0.3.4"
+version = "0.3.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "09b23093265f8d200fa7b4c2c76297f47e681c655f6f1285a8780d6a022f7431"
+checksum = "de0737333e7a9502c789a36d7c7fa6092a49895d4faa31ca5df163857ded2e9d"
 dependencies = [
  "getrandom",
  "redox_syscall",
@@ -1214,11 +1208,11 @@ checksum = "26412eb97c6b088a6997e05f69403a802a92d520de2f8e63c2b65f9e0f47c4e8"
 
 [[package]]
 name = "rust-argon2"
-version = "0.7.0"
+version = "0.8.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2bc8af4bda8e1ff4932523b94d3dd20ee30a87232323eda55903ffd71d2fb017"
+checksum = "9dab61250775933275e84053ac235621dfb739556d5c54a2f2e9313b7cf43a19"
 dependencies = [
- "base64 0.11.0",
+ "base64",
  "blake2b_simd",
  "constant_time_eq",
  "crossbeam-utils",
@@ -1500,11 +1494,12 @@ dependencies = [
 
 [[package]]
 name = "time"
-version = "0.1.43"
+version = "0.1.44"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ca8a50ef2360fbd1eeb0ecd46795a87a19024eb4b53c5dc916ca1fd95fe62438"
+checksum = "6db9e6914ab8b1ae1c260a4ae7a49b6c5611b40328a735b21862567685e73255"
 dependencies = [
  "libc",
+ "wasi 0.10.0+wasi-snapshot-preview1",
  "winapi",
 ]
 
@@ -1619,6 +1614,12 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "cccddf32554fecc6acb585f82a32a72e28b48f8c4c1883ddfeeeaa96f7d8e519"
 
 [[package]]
+name = "wasi"
+version = "0.10.0+wasi-snapshot-preview1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1a143597ca7c7793eff794def352d41792a93c481eb1042423ff7ff72ba2c31f"
+
+[[package]]
 name = "wasm-bindgen"
 version = "0.2.67"
 source = "registry+https://github.com/rust-lang/crates.io-index"
diff --git a/Cargo.toml b/Cargo.toml
index e2d561b..0f208cd 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "broot"
-version = "0.20.3"
+version = "1.0.0"
 authors = ["dystroy <denys.seguret@gmail.com>"]
 repository = "https://github.com/Canop/broot"
 documentation = "https://dystroy.org/broot"
diff --git a/src/app/app.rs b/src/app/app.rs
index 2d7a1f8..14dcb39 100644
--- a/src/app/app.rs
+++ b/src/app/app.rs
@@ -96,7 +96,9 @@ impl App {
         }
     }
 
-    /// return true when the panel has been removed (ie it wasn't the last one)
+    /// close the panel if it's not the last one
+    ///
+    /// Return true when the panel has been removed (ie it wasn't the last one)
     fn close_panel(&mut self, panel_idx: usize, screen: &Screen) -> bool {
         let active_panel_id = self.panels[self.active_panel_idx].id;
         if let Some(preview_id) = self.preview {
@@ -120,6 +122,11 @@ impl App {
         }
     }
 
+    /// remove the top state of the current panel
+    ///
+    /// Close the panel too if that was its only state.
+    /// Close nothing and return false if there's not
+    /// at least two states in the app.
     fn remove_state(&mut self, screen: &Screen) -> bool {
         self.panels[self.active_panel_idx].remove_state()
             || self.close_panel(self.active_panel_idx, screen)
@@ -155,8 +162,7 @@ impl App {
         }
     }
 
-    /// apply a command, and returns a command, which may be the same (modified or not)
-    ///  or a new one.
+    /// apply a command. Change the states but don't redraw on screen.
     fn apply_command(
         &mut self,
         w: &mut W,
@@ -365,6 +371,7 @@ impl App {
         Ok(())
     }
 
+    /// update the state of the preview, if there's some
     fn update_preview(&mut self, con: &AppContext) {
         let preview_idx = self.preview.and_then(|id| self.panel_idx(id));
         if let Some(preview_idx) = preview_idx {
@@ -377,6 +384,7 @@ impl App {
         }
     }
 
+    /// get the index of the panel at x
     fn clicked_panel_index(&self, x: u16, _y: u16, screen: &Screen) -> usize {
         let len = self.panels.len().get();
         (len * x as usize) / (screen.width as usize + 1)
diff --git a/src/app/context.rs b/src/app/context.rs
index ea2a677..40e718f 100644
--- a/src/app/context.rs
+++ b/src/app/context.rs
@@ -12,7 +12,8 @@ use {
 };
 
 /// The immutable container that can be passed around
-/// to provide the configuration things
+/// to provide the configuration things for the whole
+/// life of the App
 pub struct AppContext {
 
     /// where's the config file we're using
@@ -86,7 +87,7 @@ fn are_true_colors_available() -> bool {
     if let Ok(colorterm) = std::env::var("COLORTERM") {
         debug!("COLORTERM env variable = {:?}", colorterm);
         if colorterm.contains("truecolor") || colorterm.contains("24bit") {
-            debug!("true colors are available!");
+            debug!("true colors are available");
             true
         } else {
             false
diff --git a/src/app/panel.rs b/src/app/panel.rs
index e3e729e..91c7c49 100644
--- a/src/app/panel.rs
+++ b/src/app/panel.rs
@@ -21,6 +21,8 @@ use {
     termimad::Event,
 };
 
+/// A colon on screen containing a stack of states, the top
+/// one being visible
 pub struct Panel {
     pub id: PanelId,
     states: Vec<Box<dyn AppState>>, // stack: the last one is current
@@ -55,6 +57,8 @@ impl Panel {
         self.status = Status::from_error(text);
     }
 
+    /// apply a command on the current state, with no
+    /// effect on screen
     pub fn apply_command(
         &mut self,
         w: &mut W,
@@ -155,6 +159,7 @@ impl Panel {
         self.input.get_content()
     }
 
+    /// change the argument of the verb in the input, if there's one
     pub fn set_input_arg(&mut self, arg: String) {
         let mut command_parts = CommandParts::from(self.input.get_content());
         if let Some(invocation) = &mut command_parts.verb_invocation {
@@ -175,6 +180,7 @@ impl Panel {
         }
     }
 
+    /// render the whole panel (state, status, purpose, input, flags)
     pub fn display(
         &mut self,
         w: &mut W,
@@ -214,6 +220,9 @@ impl Panel {
         status_line::write(w, task, &self.status, &self.areas.status, panel_skin, screen)
     }
 
+    /// if a panel has a specific purpose (i.e. is here for
+    /// editing of the verb argument on another panel), render
+    /// a hint of that purpose on screen
     fn write_purpose(
         &self,
         w: &mut W,
diff --git a/src/app/panel_id.rs b/src/app/panel_id.rs
index ac16b5d..2b53875 100644
--- a/src/app/panel_id.rs
+++ b/src/app/panel_id.rs
@@ -1,5 +1,8 @@
+
+/// The unique identifiant of a panel
 #[derive(Debug, Clone, Copy, PartialEq)]
 pub struct PanelId(usize);
+
 impl From<usize> for PanelId {
     fn from(u: usize) -> Self {
         Self(u)
diff --git a/src/app/selection.rs b/src/app/selection.rs
index 6f7cd5c..9cbb3f6 100644
--- a/src/app/selection.rs
+++ b/src/app/selection.rs
@@ -7,7 +7,6 @@ use {
 /// (0 if not specified)
 pub type LineNumber = usize;
 
-
 /// light information about the currently selected
 /// file and maybe line number
 #[derive(Debug, Clone, Copy)]
diff --git a/src/app/standard_status.rs b/src/app/standard_status.rs
index 3712371..16ef43d 100644
--- a/src/app/standard_status.rs
+++ b/src/app/standard_status.rs
@@ -8,13 +8,13 @@ use {
     },
 };
 
+/// all the precomputed status which don't involve a verb
 pub struct StandardStatus {
     tree_top_focus: String, // go up (if not at root)
     tree_dir_focus: String,
     tree_dir_cd: Option<String>, // TODO check outcmd
     tree_file_open_stay: Option<String>,
     tree_file_open_leave: Option<String>,
-    // tree_file_enter: Option<String>, // defined if enter doesn't do open or alt-open
     tree_unfiltered: String,
     tree_filtered: String,
     preview_unfiltered: String, // ctrl-left to close, or a pattern to filter
diff --git a/src/app/state.rs b/src/app/state.rs
index 95f1cbb..6fa63f9 100644
--- a/src/app/state.rs
+++ b/src/app/state.rs
@@ -17,7 +17,7 @@ use {
     termimad::Area,
 };
 
-/// a whole application state, stackable to allow reverting
+/// a panel state, stackable to allow reverting
 ///  to a previous one
 pub trait AppState {
     /// called on start of on_command
@@ -237,6 +237,7 @@ pub trait AppState {
         }
     }
 
+    /// return a cmdresult asking for the opening of a preview
     fn open_preview(
         &mut self,
         prefered_mode: Option<PreviewMode>,
diff --git a/src/app/state_type.rs b/src/app/state_type.rs
index db0277f..5e4751b 100644
--- a/src/app/state_type.rs
+++ b/src/app/state_type.rs
@@ -1,7 +1,15 @@
 
+/// one of the three types of state that you could
+/// find in a panel today
 #[derive(Debug, Clone, Copy)]
 pub enum AppStateType {
+
+    /// The standard browsing tree
     Tree,
+
+    /// The help "screen"
     Help,
+
+    /// The preview panel, never alone on screen
     Preview,
 }
diff --git a/src/app/status.rs b/src/app/status.rs
index de02584..e275f07 100644
--- a/src/app/status.rs
+++ b/src/app/status.rs
@@ -1,3 +1,4 @@
+
 /// the status contains information written on the grey line
 ///  near the bottom of the screen
 #[derive(Debug, Clone)]
diff --git a/src/browser/browser_state.rs b/src/browser/browser_state.rs
index 88f8e74..9cd833b 100644
--- a/src/browser/browser_state.rs
+++ b/src/browser/browser_state.rs
@@ -63,6 +63,9 @@ impl BrowserState {
         }))
     }
 
+    /// build a cmdResult asking for the addition of a new state
+    /// being a browser state similar to the current one but with
+    /// different options
     pub fn with_new_options(
         &self,
         screen: &Screen,
diff --git a/src/clap.rs b/src/clap.rs
index 8f4b1d8..b2cebf9 100644
--- a/src/clap.rs
+++ b/src/clap.rs
@@ -6,7 +6,10 @@ pub fn clap_app() -> clap::App<'static, 'static> {
     let app = clap::App::new("broot")
         .version(env!("CARGO_PKG_VERSION"))
         .author("dystroy <denys.seguret@gmail.com>")
-        .about("A tree explorer and a customizable launcher")
+        .about(
+            "A tree explorer and a customizable launcher\n\
+            Complete documentation lives at https://dystroy.org/broot"
+        )
         .arg(clap::Arg::with_name("ROOT").help("sets the root directory"))
         // tree flags
         .arg(
diff --git a/src/cli.rs b/src/cli.rs
index ee5519e..f88493e 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -256,8 +256,7 @@ pub fn run() -> Result<Option<Launchable>, ProgramError> {
     r
 }
 
-/// wait for user input, return `true` if she
-/// didn't answer 'n'
+/// wait for user input, return `true` if they didn't answer 'n'
 pub fn ask_authorization() -> Result<bool, ProgramError> {
     let mut answer = String::new();
     io::stdin().read_line(&mut answer)?;
diff --git a/src/display/crop_writer.rs b/src/display/crop_writer.rs
index 6df5cc7..9fb431a 100644
--- a/src/display/crop_writer.rs
+++ b/src/display/crop_writer.rs
@@ -10,7 +10,7 @@ use {
     unicode_width::{UnicodeWidthChar, UnicodeWidthStr},
 };
 
-static TAB_REPLACEMENT: &'static str = "  ";
+static TAB_REPLACEMENT: &str = "  ";
 
 /// wrap a writer to ensure that at most `allowed` chars are
 /// written.
diff --git a/src/tree/sort.rs b/src/tree/sort.rs
index 1e104e6..c1dbb05 100644
--- a/src/tree/sort.rs
+++ b/src/tree/sort.rs
@@ -1,4 +1,5 @@
 
+/// A sort key.
 /// A non None sort mode implies only one level of the tree
 /// is displayed.
 /// When in None mode, paths are alpha sorted
diff --git a/src/tree/tree.rs b/src/tree/tree.rs
index 58ea218..00f371b 100644
--- a/src/tree/tree.rs
+++ b/src/tree/tree.rs
@@ -1,5 +1,3 @@
-//! In the 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 {
     super::*,
     crate::{
@@ -18,6 +16,10 @@ use {
     },
 };
 
+/// The tree which may be displayed, with onle line per visible line of the panel.
+///
+/// In the 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.
 #[derive(Debug, Clone)]
 pub struct Tree {
     pub lines: Box<[TreeLine]>,
@@ -31,6 +33,7 @@ pub struct Tree {
 
 impl Tree {
 
+    /// rebuild the tree with the same root, height, and options
     pub fn refresh(
         &mut self,
         page_height: usize,
@@ -221,7 +224,7 @@ impl Tree {
     pub fn root(&self) -> &PathBuf {
         &self.lines[0].path
     }
-    // select the line with the best matching score
+    /// select the line with the best matching score
     pub fn try_select_best_match(&mut self) {
         let mut best_score = 0;
         for (idx, line) in self.lines.iter().enumerate() {
@@ -321,7 +324,7 @@ impl Tree {
         self.git_status.is_not_computed()
     }
 
-    /// fetches the file_sums of regular files (thus avoiding the
+    /// fetch the file_sums of regular files (thus avoiding the
     /// long computation which is needed for directories)
     pub fn fetch_regular_file_sums(&mut self) {
         for i in 1..self.lines.len() {
@@ -347,8 +350,8 @@ impl Tree {
     }
 
     /// Sort files according to the sort option
-    /// (does nothing if there's none)
     ///
+    /// (does nothing if it's None)
     fn sort_siblings(&mut self) {
         if !self.options.sort.is_some() {
             return;
diff --git a/src/tree/tree_line.rs b/src/tree/tree_line.rs
index f85d081..ab1c76c 100644
--- a/src/tree/tree_line.rs
+++ b/src/tree/tree_line.rs
@@ -1,5 +1,3 @@
-//! In the 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 {
     super::*,
     crate::{
diff --git a/src/verb/external_execution.rs b/src/verb/external_execution.rs
index 3d3b0d4..cf53722 100644
--- a/src/verb/external_execution.rs
+++ b/src/verb/external_execution.rs
@@ -292,7 +292,6 @@ impl ExternalExecution {
     fn exec_token(
         &self,
         sel: Selection<'_>,
-        //file: &Path,
         other_file: &Option<PathBuf>,
         args: &Option<String>,
     ) -> Vec<String> {
@@ -313,7 +312,6 @@ impl ExternalExecution {
     pub fn shell_exec_string(
         &self,
         sel: Selection<'_>,
-        //file: &Path,
         other_file: &Option<PathBuf>,
         args: &Option<String>,
     ) -> String {
diff --git a/src/verb/internal_execution.rs b/src/verb/internal_execution.rs
index 1a2f344..ec39713 100644
--- a/src/verb/internal_execution.rs
+++ b/src/verb/internal_execution.rs
@@ -7,8 +7,16 @@ use {
 /// A verb execution definition based on an internal
 #[derive(Debug, Clone)]
 pub struct InternalExecution {
+
+    /// the internal to use
     pub internal: Internal,
+
+    /// whether to open the resulting state in a new panel
+    /// instead of the current ones
     pub bang: bool,
+
+    /// arguments
+    /// (for example `"~"` when a verb execution is `:!focus ~`)
     pub arg: Option<String>,
 }
 
diff --git a/src/verb/internal_focus.rs b/src/verb/internal_focus.rs
index 13fc8d1..6117db3 100644
--- a/src/verb/internal_focus.rs
+++ b/src/verb/internal_focus.rs
@@ -1,3 +1,5 @@
+//! utility functions to help handle the `:focus` internal
+
 use {
     super::*,
     crate::{