update settings comments

iot_verifier/src/settings.rs

@@ -15,22 +15,36 @@ pub struct Settings {
     /// Cache location for generated verified reports
     pub cache: String,
 
-    /// the base_stale period in seconds
-    /// if this is set, this value will be added to the entropy and report
-    /// stale periods and is to prevent data being unnecessarily purged
-    /// in the event the verifier is down for an extended period of time
+    /// the base_stale period
+    /// this is used to determine the minimum period for
+    /// entropy, witness and beacon reports after which they will be deemed stale
+    /// and considered for purging by the purger
+    /// if the verifier is down for an extended period of time, extend this value
+    /// to prevent data being unnecessarily purged and unprocessed historical data being lost
     #[serde(with = "humantime_serde", default = "default_base_stale_period")]
     pub base_stale_period: Duration,
 
-    /// the period after which a beacon report in the DB will be deemed stale
+    /// beacon_stale_period is added to the base stale period
+    /// to determine the final stale period for beacon reports
+    /// each report type has its own stale period to enable report specific
+    /// stale periods
+    /// TODO: this fine grained control is overkill - one stale period to rule them all is sufficient
     #[serde(with = "humantime_serde", default = "default_beacon_stale_period")]
     pub beacon_stale_period: Duration,
 
-    /// the period after which a witness report in the DB will be deemed stale
+    /// witness_stale_period is added to the base stale period
+    /// to determine the final stale period for witness reports
+    /// each report type has its own stale period to enable report specific
+    /// stale periods
+    /// TODO: this fine grained control is overkill - one stale period to rule them all is sufficient
     #[serde(with = "humantime_serde", default = "default_witness_stale_period")]
     pub witness_stale_period: Duration,
 
-    /// the period after which an entropy report in the DB will be deemed stale
+    /// entropy_stale_period is added to the base stale period
+    /// to determine the final stale period for entropy reports
+    /// each report type has its own stale period to enable report specific
+    /// stale periods
+    /// TODO: this fine grained control is overkill - one stale period to rule them all is sufficient
     #[serde(with = "humantime_serde", default = "default_entropy_stale_period")]
     pub entropy_stale_period: Duration,
 
@@ -44,7 +58,7 @@ pub struct Settings {
     pub denylist: denylist::Settings,
     pub price_tracker: price::price_tracker::Settings,
 
-    /// Reward period in hours. (Default to 24)
+    /// Reward period in hours
     #[serde(with = "humantime_serde", default = "default_reward_period")]
     pub reward_period: Duration,
 
@@ -56,9 +70,11 @@ pub struct Settings {
     #[serde(default = "default_max_witnesses_per_poc")]
     pub max_witnesses_per_poc: u64,
 
-    /// The cadence at which hotspots are permitted to beacon
-    /// this should be a factor of 24 so that we can have clear
-    /// beaconing bucket sizes
+    /// Gateways are permitted to beacon at a cadence of 1 per beacon_interval
+    /// Think of this interval as a window in which a gateway can beacon once
+    /// and only once at any point within any one window
+    /// this should be a factor of 24 so that we can have evenly spread
+    /// beaconing window sizes
     #[serde(with = "humantime_serde", default = "default_beacon_interval")]
     pub beacon_interval: Duration,
 
@@ -70,7 +86,6 @@ pub struct Settings {
     pub ingestor_rollup_time: Duration,
 
     /// window width for the poc report loader
-    /// each poll the loader will load reports from start time to start time + window width
     /// NOTE: the window width should be as a minimum equal to the ingestor roll up period
     ///       any less and the verifier will potentially miss incoming reports
     #[serde(with = "humantime_serde", default = "default_poc_loader_window_width")]
@@ -80,38 +95,42 @@ pub struct Settings {
     #[serde(with = "humantime_serde", default = "default_poc_loader_poll_time")]
     pub poc_loader_poll_time: Duration,
 
-    /// max window age for the poc report loader ( in seconds )
+    /// max window age for the poc report loader
     /// the starting point of the window will never be older than now - max age
     /// if ingesting historic data, this value should be set appropriately
+    /// NOTE: this was added mostly to support running the verifier locally
+    /// and doing so intermittently which results in the verifier being behind
+    /// with this setting it ensures we can ignore data older than the max lookback age
+    /// TODO: this setting should be considered for removal in the future
     #[serde(
         with = "humantime_serde",
         default = "default_loader_window_max_lookback_age"
     )]
     pub loader_window_max_lookback_age: Duration,
 
-    /// File store poll interval for incoming entropy reports, in seconds
+    /// File store poll interval for incoming entropy reports
     #[serde(with = "humantime_serde", default = "default_entropy_interval")]
     pub entropy_interval: Duration,
 
-    /// File store poll interval for incoming packets, in seconds. (Default 15 minutes)
+    /// File store poll interval for incoming packets, in seconds
     #[serde(with = "humantime_serde", default = "default_packet_interval")]
     pub packet_interval: Duration,
 
     /// the max number of times a beacon report will be retried
-    /// after this the report will be ignored and eventually be purged
+    /// after which the report will be ignored and eventually be purged
     #[serde(default = "default_beacon_max_retries")]
     pub beacon_max_retries: u64,
 
     /// the max number of times a witness report will be retried
-    /// after this the report will be ignored and eventually be purged
+    /// after which the report will be ignored and eventually be purged
     #[serde(default = "default_witness_max_retries")]
     pub witness_max_retries: u64,
 
-    /// interval at which gateways are refreshed
+    /// interval at which cached gateways are refreshed from iot config
     #[serde(with = "humantime_serde", default = "default_gateway_refresh_interval")]
     pub gateway_refresh_interval: Duration,
 
-    /// interval at which region params in the cache are refreshed
+    /// interval at which cached region params are refreshed from iot config
     #[serde(
         with = "humantime_serde",
         default = "default_region_params_refresh_interval"