From 43991b5e24dcd7d80a3aaef601805dc892ee2307 Mon Sep 17 00:00:00 2001
From: Denis Nutiu <denis.nutiu@gmail.com>
Date: Mon, 26 Feb 2024 21:34:57 +0200
Subject: [PATCH] refactor: add docstrings to calculation

---
 src/calculation.rs | 41 +++++++++++++++++++++++++++++------------
 1 file changed, 29 insertions(+), 12 deletions(-)

diff --git a/src/calculation.rs b/src/calculation.rs
index 14c3e1c..43ee7bf 100644
--- a/src/calculation.rs
+++ b/src/calculation.rs
@@ -5,9 +5,13 @@ use core::time::Duration;
 pub struct Calculation {}
 
 impl Calculation {
-    pub fn heater_resistance(calibration_data: &CalibrationData, ambient_temperature: i8, temperature: u16) -> u8 {
+    /// Calculates and returns the sensor's heater resistance.
+    /// * `calibration_data` - The calibration data of the sensor.
+    /// * `ambient_temperature` - The ambient temperature.
+    /// * `heater_temperature` - The heater temperature.
+    pub fn heater_resistance(calibration_data: &CalibrationData, ambient_temperature: i8, heater_temperature: u16) -> u8 {
         // cap temperature
-        let temp = if temperature <= 400 { temperature } else { 400 };
+        let temp = if heater_temperature <= 400 { heater_temperature } else { 400 };
 
         let var1 = ambient_temperature as i32 * calibration_data.par_gh3 as i32 / 1000i32 * 256i32;
         let var2 = (calibration_data.par_gh1 as i32 + 784i32)
@@ -20,9 +24,10 @@ impl Calculation {
         ((heatr_res_x100 + 50i32) / 100i32) as u8
     }
 
+    /// Calculates and returns the heater duration.
+    /// * `duration` The duration time
     pub fn heater_duration(duration: Duration) -> u8 {
         let mut factor: u8 = 0u8;
-        // TODO replace once https://github.com/rust-lang/rust/pull/50167 has been merged
         const MILLIS_PER_SEC: u64 = 1_000;
         const NANOS_PER_MILLI: u64 = 1_000_000;
         let mut dur = (duration.as_secs() as u64 * MILLIS_PER_SEC)
@@ -41,9 +46,9 @@ impl Calculation {
         }
     }
 
-    ///
-    /// * `calib` - Calibration data used during initalization
-    /// * `temp_adc`
+    /// Calculates and returns the sensor temperature.
+    /// * `calibration_data` - Calibration data used during initialization
+    /// * `temp_adc`    - The temperature reading of the analog to digital converter.
     /// * `temp_offset` - If set, the temperature t_fine will be increased by given
     ///                   value in celsius. Temperature offset in Celsius, e.g. 4, -8, 1.25
     pub fn temperature(
@@ -70,7 +75,11 @@ impl Calculation {
         (calc_temp, t_fine)
     }
 
-    pub fn pressure(calibration_data: &CalibrationData, t_fine: i32, pres_adc: u32) -> u32 {
+    /// Calculates and returns the pressure of the sensor.
+    ///
+    /// * `t_fine` - The resolution temperature obtained after applying calibration data.
+    /// * `pressure_adc` - The pressure value as returned by the analog to digital converter.
+    pub fn pressure(calibration_data: &CalibrationData, t_fine: i32, pressure_adc: u32) -> u32 {
         let mut var1: i32 = (t_fine >> 1) - 64000;
         let mut var2: i32 = ((((var1 >> 2) * (var1 >> 2)) >> 11) * calibration_data.par_p6 as i32) >> 2;
         var2 += (var1 * (calibration_data.par_p5 as i32)) << 1;
@@ -80,7 +89,7 @@ impl Calculation {
             + ((calibration_data.par_p2 as i32 * var1) >> 1i32);
         var1 >>= 18i32;
         var1 = ((32768i32 + var1) * calibration_data.par_p1 as i32) >> 15i32;
-        let mut pressure_comp: i32 = 1048576u32.wrapping_sub(pres_adc) as i32;
+        let mut pressure_comp: i32 = 1048576u32.wrapping_sub(pressure_adc) as i32;
         pressure_comp = ((pressure_comp - (var2 >> 12i32)) as u32).wrapping_mul(3125u32) as i32;
         if pressure_comp >= 0x40000000i32 {
             pressure_comp = ((pressure_comp as u32).wrapping_div(var1 as u32) << 1i32) as i32;
@@ -100,9 +109,13 @@ impl Calculation {
         pressure_comp as u32
     }
 
-    pub fn humidity(calibration_data: &CalibrationData, t_fine: i32, hum_adc: u16) -> u32 {
+    /// Calculates and returns the humidity of the sensor.
+    ///
+    /// * `t_fine` - The resolution temperature obtained after applying calibration data.
+    /// * `humidity_adc` - The humidity value as returned by the analog to digital converter.
+    pub fn humidity(calibration_data: &CalibrationData, t_fine: i32, humidity_adc: u16) -> u32 {
         let temp_scaled: i32 = (t_fine * 5i32 + 128i32) >> 8i32;
-        let var1: i32 = hum_adc as i32
+        let var1: i32 = humidity_adc as i32
             - calibration_data.par_h1 as i32 * 16i32
             - ((temp_scaled * calibration_data.par_h3 as i32 / 100i32) >> 1i32);
         let var2: i32 = (calibration_data.par_h2 as i32
@@ -124,7 +137,11 @@ impl Calculation {
         calc_hum as u32
     }
 
-    pub fn gas_resistance(calibration_data: &CalibrationData, gas_res_adc: u16, gas_range: u8) -> u32 {
+    /// Calculates and returns the gas resistance.
+    ///
+    /// * `gas_resistance_adc` - The gas resistance reading from the analog to digital converter.
+    /// * `gas_range` - The lookup table gas range.
+    pub fn gas_resistance(calibration_data: &CalibrationData, gas_resistance_adc: u16, gas_range: u8) -> u32 {
         let lookup_table1: [u32; 16] = [
             2147483647u32,
             2147483647u32,
@@ -164,7 +181,7 @@ impl Calculation {
         let var1: i64 = ((1340 + 5 * calibration_data.range_sw_err as i64)
             * lookup_table1[gas_range as usize] as i64)
             >> 16;
-        let var2: u64 = (((gas_res_adc as i64) << 15) - 16777216 + var1) as u64;
+        let var2: u64 = (((gas_resistance_adc as i64) << 15) - 16777216 + var1) as u64;
         let var3: i64 = (lookup_table2[gas_range as usize] as i64 * var1) >> 9;
         let calc_gas_res: u32 = ((var3 + ((var2 as i64) >> 1i64)) / var2 as i64) as u32;
         calc_gas_res