From 729afa388610f82fe4bd6784d8e5b70aac47439a Mon Sep 17 00:00:00 2001
From: Luni-4 <luni-4@hotmail.it>
Date: Fri, 6 Nov 2020 15:09:21 +0100
Subject: [PATCH] Clarify the documentation of some metrics

---
 src/metrics/halstead.rs | 45 ++++++++++++++++++++++++++++++++++++++---
 src/metrics/mi.rs       | 10 ++++++---
 2 files changed, 49 insertions(+), 6 deletions(-)

diff --git a/src/metrics/halstead.rs b/src/metrics/halstead.rs
index 3c1b334c0..bf96d09e9 100644
--- a/src/metrics/halstead.rs
+++ b/src/metrics/halstead.rs
@@ -171,9 +171,12 @@ impl Stats {
         self.u_operands() + self.u_operators()
     }
 
-    /// Returns the program volume
+    /// Returns the program volume.
+    ///
+    /// Unit of measurement: bits
     #[inline(always)]
     pub fn volume(&self) -> f64 {
+        // Assumes a uniform binary encoding for the vocabulary is used.
         self.length() * self.vocabulary().log2()
     }
 
@@ -195,15 +198,51 @@ impl Stats {
         self.difficulty() * self.volume()
     }
 
-    /// Returns the estimated time required to program
+    /// Returns the estimated time required to program.
+    ///
+    /// Unit of measurement: seconds
     #[inline(always)]
     pub fn time(&self) -> f64 {
+        // The floating point `18.` aims to describe the processing rate of the
+        // human brain. It is called Stoud number, S, and its
+        // unit of measurement is moments/seconds.
+        // A moment is the time required by the human brain to carry out the
+        // most elementary decision.
+        // 5 <= S <= 20. Halstead uses 18.
+        // The value of S has been empirically developed from psychological
+        // reasoning, and its recommended value for
+        // programming applications is 18.
+        //
+        // Source: https://www.geeksforgeeks.org/software-engineering-halsteads-software-metrics/
         self.effort() / 18.
     }
 
-    /// Returns the number of delivered bugs
+    /// Returns the estimated number of delivered bugs.
+    ///
+    /// This metric represents the average amount of work a programmer can do
+    /// without introducing an error.
     #[inline(always)]
     pub fn bugs(&self) -> f64 {
+        // The floating point `3000.` represents the number of elementary
+        // mental discriminations.
+        // A mental discrimination, in psychology, is the ability to perceive
+        // and respond to differences among stimuli.
+        //
+        // The value above is obtained starting from a constant that
+        // is different for every language and assumes that natural language is
+        // the language of the brain.
+        // For programming languages, the English language constant
+        // has been considered.
+        //
+        // After every 3000 mental discriminations a result is produced.
+        // This result, whether correct or incorrect, is more than likely
+        // either used as an input for the next operation or is output to the
+        // environment.
+        // If incorrect the error should become apparent.
+        // Thus, an opportunity for error occurs every 3000
+        // mental discriminations.
+        //
+        // Source: https://docs.lib.purdue.edu/cgi/viewcontent.cgi?article=1145&context=cstech
         self.effort().powf(2. / 3.) / 3000.
     }
 }
diff --git a/src/metrics/mi.rs b/src/metrics/mi.rs
index 81d723116..ffc6f29e8 100644
--- a/src/metrics/mi.rs
+++ b/src/metrics/mi.rs
@@ -49,7 +49,9 @@ impl fmt::Display for Stats {
 impl Stats {
     pub(crate) fn merge(&mut self, _other: &Stats) {}
 
-    /// Returns the `Mi` metric calculated using the original formula
+    /// Returns the `Mi` metric calculated using the original formula.
+    ///
+    /// Its value can be negative.
     #[inline(always)]
     pub fn mi_original(&self) -> f64 {
         // http://www.projectcodemeter.com/cost_estimation/help/GL_maintainability.htm
@@ -57,7 +59,9 @@ impl Stats {
     }
 
     /// Returns the `Mi` metric calculated using the derivative formula
-    /// employed by the Software Engineering Insitute (SEI)
+    /// employed by the Software Engineering Insitute (SEI).
+    ///
+    /// Its value can be negative.
     #[inline(always)]
     pub fn mi_sei(&self) -> f64 {
         // http://www.projectcodemeter.com/cost_estimation/help/GL_maintainability.htm
@@ -66,7 +70,7 @@ impl Stats {
     }
 
     /// Returns the `Mi` metric calculated using the derivative formula
-    /// employed by Microsoft Visual Studio
+    /// employed by Microsoft Visual Studio.
     #[inline(always)]
     pub fn mi_visual_studio(&self) -> f64 {
         // http://www.projectcodemeter.com/cost_estimation/help/GL_maintainability.htm