From 4ac3b432602259efbd79efefbd016eebb7966675 Mon Sep 17 00:00:00 2001
From: Clement Tsang <34804052+ClementTsang@users.noreply.github.com>
Date: Sat, 24 Jun 2023 05:36:36 +0000
Subject: [PATCH] docs: update time-related documentation (#1222)

* docs: update time-related documentation

* fix retention too
---
 .../configuration/command-line-flags.md       | 84 +++++++++----------
 .../configuration/config-file/flags.md        |  2 +-
 sample_configs/default_config.toml            |  2 +-
 src/args.rs                                   | 16 ++--
 src/options.rs                                | 32 ++++---
 5 files changed, 73 insertions(+), 63 deletions(-)

diff --git a/docs/content/configuration/command-line-flags.md b/docs/content/configuration/command-line-flags.md
index cbaf6ee6..e0a7192f 100644
--- a/docs/content/configuration/command-line-flags.md
+++ b/docs/content/configuration/command-line-flags.md
@@ -3,45 +3,45 @@
 The following flags can be provided to bottom in the command line to change the behaviour of the program. You can also
 see information on these flags by running `btm -h`, or run `btm --help` to display more detailed information on each flag:
 
-| Flag                                | Behaviour                                                       |
-| ----------------------------------- | --------------------------------------------------------------- |
-| --autohide_time                     | Temporarily shows the time scale in graphs.                     |
-| -b, --basic                         | Hides graphs and uses a more basic look.                        |
-| --battery                           | Shows the battery widget.                                       |
-| -S, --case_sensitive                | Enables case sensitivity by default.                            |
-| -c, --celsius                       | Sets the temperature type to Celsius.                           |
-| --color <COLOR SCHEME>              | Use a color scheme, use --help for info.                        |
-| -C, --config <CONFIG PATH>          | Sets the location of the config file.                           |
-| -u, --current_usage                 | Sets process CPU% to be based on current CPU%.                  |
-| -t, --default_time_value <TIME>     | Default time value for graphs.                                  |
-| --default_widget_count <INT>        | Sets the n'th selected widget type as the default.              |
-| --default_widget_type <WIDGET TYPE> | Sets the default widget type, use --help for info.              |
-| --disable_advanced_kill             | Hides advanced process killing.                                 |
-| --disable_click                     | Disables mouse clicks.                                          |
-| -m, --dot_marker                    | Uses a dot marker for graphs.                                   |
-| --enable_cache_memory               | Enable collecting and displaying cache and buffer memory.       |
-| --enable_gpu_memory                 | Enable collecting and displaying GPU memory usage.              |
-| -e, --expanded                      | Expand the default widget upon starting the app.                |
-| -f, --fahrenheit                    | Sets the temperature type to Fahrenheit.                        |
-| -g, --group                         | Groups processes with the same name by default.                 |
-| -a, --hide_avg_cpu                  | Hides the average CPU usage.                                    |
-| --hide_table_gap                    | Hides spacing between table headers and entries.                |
-| --hide_time                         | Hides the time scale.                                           |
-| -k, --kelvin                        | Sets the temperature type to Kelvin.                            |
-| -l, --left_legend                   | Puts the CPU chart legend to the left side.                     |
-| --mem_as_value                      | Defaults to showing process memory usage by value.              |
-| --network_use_binary_prefix         | Displays the network widget with binary prefixes.               |
-| --network_use_bytes                 | Displays the network widget using bytes.                        |
-| --network_use_log                   | Displays the network widget with a log scale.                   |
-| --process_command                   | Show processes as their commands by default.                    |
-| -r, --rate <MS>                     | Sets a refresh rate in ms.                                      |
-| -R, --regex                         | Enables regex by default.                                       |
-| --retention <TIME>                  | The timespan of data kept.                                      |
-| --show_table_scroll_position        | Shows the scroll position tracker in table widgets.             |
-| -d, --time_delta <TIME>             | The amount of time changed upon zooming.                        |
-| -T, --tree                          | Defaults the process widget be in tree mode.                    |
-| -n, --unnormalized_cpu              | Show process CPU% without normalizing over the number of cores. |
-| --use_old_network_legend            | DEPRECATED - uses a separate network legend.                    |
-| -V, --version                       | Prints version information.                                     |
-| -W, --whole_word                    | Enables whole-word matching by default.                         |
-| -h, --help                          | Print help (see more with '--help')                             |
+| Flag                                | Behaviour                                                             |
+| ----------------------------------- | --------------------------------------------------------------------- |
+| --autohide_time                     | Temporarily shows the time scale in graphs.                           |
+| -b, --basic                         | Hides graphs and uses a more basic look.                              |
+| --battery                           | Shows the battery widget.                                             |
+| -S, --case_sensitive                | Enables case sensitivity by default.                                  |
+| -c, --celsius                       | Sets the temperature type to Celsius.                                 |
+| --color <COLOR SCHEME>              | Use a color scheme, use --help for info.                              |
+| -C, --config <CONFIG PATH>          | Sets the location of the config file.                                 |
+| -u, --current_usage                 | Sets process CPU% to be based on current CPU%.                        |
+| -t, --default_time_value <TIME>     | Default time value for graphs.                                        |
+| --default_widget_count <INT>        | Sets the n'th selected widget type as the default.                    |
+| --default_widget_type <WIDGET TYPE> | Sets the default widget type, use --help for info.                    |
+| --disable_advanced_kill             | Hides advanced process killing.                                       |
+| --disable_click                     | Disables mouse clicks.                                                |
+| -m, --dot_marker                    | Uses a dot marker for graphs.                                         |
+| --enable_cache_memory               | Enable collecting and displaying cache and buffer memory.             |
+| --enable_gpu_memory                 | Enable collecting and displaying GPU memory usage.                    |
+| -e, --expanded                      | Expand the default widget upon starting the app.                      |
+| -f, --fahrenheit                    | Sets the temperature type to Fahrenheit.                              |
+| -g, --group                         | Groups processes with the same name by default.                       |
+| -a, --hide_avg_cpu                  | Hides the average CPU usage.                                          |
+| --hide_table_gap                    | Hides spacing between table headers and entries.                      |
+| --hide_time                         | Hides the time scale.                                                 |
+| -k, --kelvin                        | Sets the temperature type to Kelvin.                                  |
+| -l, --left_legend                   | Puts the CPU chart legend to the left side.                           |
+| --mem_as_value                      | Defaults to showing process memory usage by value.                    |
+| --network_use_binary_prefix         | Displays the network widget with binary prefixes.                     |
+| --network_use_bytes                 | Displays the network widget using bytes.                              |
+| --network_use_log                   | Displays the network widget with a log scale.                         |
+| --process_command                   | Show processes as their commands by default.                          |
+| -r, --rate <TIME>                   | Sets the data refresh rate.                                           |
+| -R, --regex                         | Enables regex by default.                                             |
+| --retention <TIME>                  | The timespan of data stored.                                          |
+| --show_table_scroll_position        | Shows the scroll position tracker in table widgets.                   |
+| -d, --time_delta <TIME>             | The amount of time changed upon zooming.                              |
+| -T, --tree                          | Defaults the process widget be in tree mode.                          |
+| -n, --unnormalized_cpu              | Show process CPU% usage without normalizing over the number of cores. |
+| --use_old_network_legend            | DEPRECATED - uses a separate network legend.                          |
+| -V, --version                       | Prints version information.                                           |
+| -W, --whole_word                    | Enables whole-word matching by default.                               |
+| -h, --help                          | Print help (see more with '--help')                                   |
diff --git a/docs/content/configuration/config-file/flags.md b/docs/content/configuration/config-file/flags.md
index fd919bea..d5466041 100644
--- a/docs/content/configuration/config-file/flags.md
+++ b/docs/content/configuration/config-file/flags.md
@@ -20,7 +20,7 @@ each time:
 | `basic`                      | Boolean                                                                                        | Hides graphs and uses a more basic look.                                             |
 | `use_old_network_legend`     | Boolean                                                                                        | DEPRECATED - uses the older network legend.                                          |
 | `battery`                    | Boolean                                                                                        | Shows the battery widget.                                                            |
-| `rate`                       | Unsigned Int (represents milliseconds)                                                         | Sets a refresh rate in ms.                                                           |
+| `rate`                       | Unsigned Int (represents milliseconds) or String (represents human time)                       | Sets a refresh rate in ms.                                                           |
 | `default_time_value`         | Unsigned Int (represents milliseconds) or String (represents human time)                       | Default time value for graphs in ms.                                                 |
 | `time_delta`                 | Unsigned Int (represents milliseconds) or String (represents human time)                       | The amount in ms changed upon zooming.                                               |
 | `hide_time`                  | Boolean                                                                                        | Hides the time scale.                                                                |
diff --git a/sample_configs/default_config.toml b/sample_configs/default_config.toml
index 74353b3c..e7b4058e 100644
--- a/sample_configs/default_config.toml
+++ b/sample_configs/default_config.toml
@@ -12,7 +12,7 @@
 # Whether to use dot markers rather than braille.
 #dot_marker = false
 # The update rate of the application.
-#rate = 1000
+#rate = "1s"
 # Whether to put the CPU legend to the left.
 #left_legend = false
 # Whether to set CPU% on a process to be based on the total CPU or just current usage.
diff --git a/src/args.rs b/src/args.rs
index b384acc0..88cfe3fb 100644
--- a/src/args.rs
+++ b/src/args.rs
@@ -149,9 +149,9 @@ pub fn build_app() -> Command {
         .short('n')
         .long("unnormalized_cpu")
         .action(ArgAction::SetTrue)
-        .help("Show process CPU% without normalizing over the number of cores.")
+        .help("Show process CPU% usage without normalizing over the number of cores.")
         .long_help(
-            "Shows process CPU usage without averaging over the number of CPU cores in the system.",
+            "Shows all process CPU% usage without averaging over the number of CPU cores in the system.",
         );
 
     let disable_click = Arg::new("disable_click")
@@ -304,7 +304,7 @@ Defaults to \"default\".
         .value_name("TIME")
         .help("Default time value for graphs.")
         .long_help(
-            "Default time value for graphs. The minimum time is 30s, and the default is 60s.",
+            "Default time value for graphs. Takes a number in milliseconds or a human duration (e.g. 60s). The minimum time is 30s, and the default is 60s.",
         );
 
     // TODO: Charts are broken in the manpage
@@ -352,9 +352,9 @@ use CPU (3) as the default instead.
         .short('r')
         .long("rate")
         .action(ArgAction::Set)
-        .value_name("MS")
+        .value_name("TIME")
         .help("Sets the data refresh rate.")
-        .long_help("Sets the data refresh rate. The minimum is 250ms, and defaults to 1000ms. Smaller values may take more computer resources.");
+        .long_help("Sets the data refresh rate. Takes a number in milliseconds or a human duration (e.g. 5s). The minimum is 250ms, and defaults to 1000ms. Smaller values may take more computer resources.");
 
     let time_delta = Arg::new("time_delta")
         .short('d')
@@ -362,7 +362,7 @@ use CPU (3) as the default instead.
         .action(ArgAction::Set)
         .value_name("TIME")
         .help("The amount of time changed upon zooming.")
-        .long_help("The amount of time changed when zooming in/out. The minimum is 1s, and defaults to 15s.");
+        .long_help("The amount of time changed when zooming in/out. Takes a number in milliseconds or a human duration (e.g. 30s). The minimum is 1s, and defaults to 15s.");
 
     let tree = Arg::new("tree")
         .short('T')
@@ -395,8 +395,8 @@ use CPU (3) as the default instead.
         .long("retention")
         .action(ArgAction::Set)
         .value_name("TIME")
-        .help("The timespan of data kept.")
-        .long_help("How much data is stored at once in terms of time. Takes in human-readable time spans (e.g. 10m, 1h), with a minimum of 1 minute. Note higher values will take up more memory. Defaults to 10 minutes.");
+        .help("The timespan of data stored.")
+        .long_help("How much data is stored at once in terms of time. Takes a number in milliseconds or a human duration (e.g. 20m), with a minimum of 1 minute. Note higher values will take up more memory. Defaults to 10 minutes.");
 
     let version = Arg::new("version")
         .short('V')
diff --git a/src/options.rs b/src/options.rs
index 412748a6..26b21d7f 100644
--- a/src/options.rs
+++ b/src/options.rs
@@ -102,9 +102,7 @@ pub struct ConfigFlags {
     network_use_binary_prefix: Option<bool>,
     enable_gpu_memory: Option<bool>,
     enable_cache_memory: Option<bool>,
-    #[serde(with = "humantime_serde")]
-    #[serde(default)]
-    retention: Option<Duration>,
+    retention: Option<StringOrNum>,
 }
 
 #[derive(Clone, Debug, Default, Deserialize, Serialize)]
@@ -200,7 +198,7 @@ pub fn build_app(
     let config = &config;
 
     let retention_ms =
-        get_retention_ms(matches, config).context("Update `retention` in your config file.")?;
+        get_retention(matches, config).context("Update `retention` in your config file.")?;
     let autohide_time = is_flag_enabled!(autohide_time, matches, config);
     let default_time_value = get_default_time_value(matches, config, retention_ms)
         .context("Update 'default_time_value' in your config file.")?;
@@ -887,16 +885,17 @@ fn get_network_scale_type(matches: &ArgMatches, config: &Config) -> AxisScaling
     AxisScaling::Linear
 }
 
-fn get_retention_ms(matches: &ArgMatches, config: &Config) -> error::Result<u64> {
+fn get_retention(matches: &ArgMatches, config: &Config) -> error::Result<u64> {
     const DEFAULT_RETENTION_MS: u64 = 600 * 1000; // Keep 10 minutes of data.
 
     if let Some(retention) = matches.get_one::<String>("retention") {
-        humantime::parse_duration(retention)
-            .map(|dur| dur.as_millis() as u64)
-            .map_err(|err| BottomError::ConfigError(format!("invalid retention duration: {err:?}")))
+        try_parse_ms(retention)
     } else if let Some(flags) = &config.flags {
-        if let Some(retention) = flags.retention {
-            Ok(retention.as_millis() as u64)
+        if let Some(retention) = &flags.retention {
+            Ok(match retention {
+                StringOrNum::String(s) => try_parse_ms(s)?,
+                StringOrNum::Num(n) => *n,
+            })
         } else {
             Ok(DEFAULT_RETENTION_MS)
         }
@@ -913,7 +912,9 @@ mod test {
     use crate::{
         app::App,
         canvas::canvas_styling::CanvasStyling,
-        options::{get_default_time_value, get_update_rate, try_parse_ms, ConfigFlags},
+        options::{
+            get_default_time_value, get_retention, get_update_rate, try_parse_ms, ConfigFlags,
+        },
     };
 
     #[test]
@@ -999,6 +1000,7 @@ mod test {
             time_delta: Some("2 min".to_string().into()),
             default_time_value: Some("300s".to_string().into()),
             rate: Some("1s".to_string().into()),
+            retention: Some("10m".to_string().into()),
             ..Default::default()
         };
 
@@ -1015,6 +1017,8 @@ mod test {
         );
 
         assert_eq!(get_update_rate(&matches, &config), Ok(1000));
+
+        assert_eq!(get_retention(&matches, &config), Ok(600000));
     }
 
     #[test]
@@ -1027,6 +1031,7 @@ mod test {
             time_delta: Some("120000".to_string().into()),
             default_time_value: Some("300000".to_string().into()),
             rate: Some("1000".to_string().into()),
+            retention: Some("600000".to_string().into()),
             ..Default::default()
         };
 
@@ -1043,6 +1048,8 @@ mod test {
         );
 
         assert_eq!(get_update_rate(&matches, &config), Ok(1000));
+
+        assert_eq!(get_retention(&matches, &config), Ok(600000));
     }
 
     #[test]
@@ -1055,6 +1062,7 @@ mod test {
             time_delta: Some(120000.into()),
             default_time_value: Some(300000.into()),
             rate: Some(1000.into()),
+            retention: Some(600000.into()),
             ..Default::default()
         };
 
@@ -1071,6 +1079,8 @@ mod test {
         );
 
         assert_eq!(get_update_rate(&matches, &config), Ok(1000));
+
+        assert_eq!(get_retention(&matches, &config), Ok(600000));
     }
 
     fn create_app(config: Config, matches: ArgMatches) -> App {