docs: update time-related documentation (#1222)

* docs: update time-related documentation

* fix retention too

docs/content/configuration/command-line-flags.md

@@ -4,7 +4,7 @@ The following flags can be provided to bottom in the command line to change the
 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.                                             |
@@ -34,13 +34,13 @@ see information on these flags by running `btm -h`, or run `btm --help` to displ
 | --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, --rate <TIME>                   | Sets the data refresh rate.                                           |
 | -R, --regex                         | Enables regex by default.                                             |
-| --retention <TIME>                  | The timespan of data kept.                                      |
+| --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% without normalizing over the number of cores. |
+| -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.                               |

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.                                                                |

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.

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.")
+        .help("The timespan of data stored.")
-        .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.");
+        .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')

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")]
+    retention: Option<StringOrNum>,
-    #[serde(default)]
-    retention: Option<Duration>,
 }
 
 #[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)
+        try_parse_ms(retention)
-            .map(|dur| dur.as_millis() as u64)
-            .map_err(|err| BottomError::ConfigError(format!("invalid retention duration: {err:?}")))
     } else if let Some(flags) = &config.flags {
-        if let Some(retention) = flags.retention {
+        if let Some(retention) = &flags.retention {
-            Ok(retention.as_millis() as u64)
+            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 {