doc: update example in README and add missing docs in code

README.md

@@ -32,10 +32,20 @@ use distimate::prelude::*;
 use distimate::Pert;
 
 fn main() {
-    let pert = Pert::new(1.0, 2.0, 3.0).unwrap();
+    // Create a PERT distribution for a task estimated to take
-    println!("Mean: {}", pert.mean().unwrap());
+    // between 1 and 3 days, most likely 2 days
-    println!("Variance: {}", pert.variance().unwrap());
+    let task_duration = Pert::new(1.0, 2.0, 3.0).unwrap();
-    println!("95th percentile: {}", pert.inverse_cdf(0.95));
+
+    println!("Expected duration: {:.2} days", task_duration.expected_value());
+    println!("Optimistic estimate (P5): {:.2} days", task_duration.optimistic_estimate());
+    println!("Pessimistic estimate (P95): {:.2} days", task_duration.pessimistic_estimate());
+    println!("Probability of completing within 2.5 days: {:.2}%",
+             task_duration.probability_of_completion(2.5) * 100.0);
+    println!("Risk of exceeding 2.5 days: {:.2}%",
+             task_duration.risk_of_overrun(2.5) * 100.0);
+
+    let (lower, upper) = task_duration.confidence_interval(0.9);
+    println!("90% Confidence Interval: {:.2} to {:.2} days", lower, upper);
 }
 ```
 

src/estimation_distribution.rs

@@ -142,6 +142,33 @@ pub trait EstimationDistribution:
         self.std_dev().unwrap()
     }
 
+    /// Calculates the probability of completing a task or project by a given estimate.
+    ///
+    /// This method computes the probability that the actual value will be less than or equal to
+    /// the provided estimate. It's particularly useful in project management and risk analysis
+    /// to quantify the likelihood of meeting deadlines or budget targets.
+    ///
+    /// The probability of completion is equivalent to the cumulative distribution function (CDF)
+    /// evaluated at the given estimate.
+    ///
+    /// # Arguments
+    ///
+    /// * `estimate` - The point estimate to evaluate the probability against.
+    ///
+    /// # Returns
+    ///
+    /// A float between 0 and 1 representing the probability of completing by the given estimate.
+    ///
+    /// # Examples
+    ///
+    /// ```
+    /// use distimate::prelude::*;
+    /// use distimate::Pert;
+    /// use approx::assert_relative_eq;
+    ///
+    /// let pert = Pert::new(1.0, 2.0, 3.0).unwrap();
+    /// assert_relative_eq!(pert.probability_of_completion(2.5), 0.8436, epsilon = 1e-4);
+    /// ```
     fn probability_of_completion(&self, estimate: f64) -> f64 {
         self.cdf(estimate)
     }