From 81a13ca4a05f8aff267ef002c6bc04de4c9bcfd1 Mon Sep 17 00:00:00 2001
From: Alix ANNERAUD <alix@anneraud.fr>
Date: Wed, 9 Oct 2024 19:10:16 +0200
Subject: [PATCH] Write documentation for duration

---
 Modules/Shared/src/Duration.rs | 97 ++++++++++++++++++++++++++++++++++
 1 file changed, 97 insertions(+)

diff --git a/Modules/Shared/src/Duration.rs b/Modules/Shared/src/Duration.rs
index b81b2a8..47a9792 100644
--- a/Modules/Shared/src/Duration.rs
+++ b/Modules/Shared/src/Duration.rs
@@ -3,6 +3,11 @@ use core::{
     time::Duration,
 };
 
+/// Represents a duration of time.
+///
+/// A duration is the amount of time between two instants. It can only be positive.
+/// Its maximum precision is nanoseconds.
+/// It is deeply inspired by the [`core::time::Duration`] type.
 #[derive(Clone, Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Default)]
 pub struct Duration_type {
     Seconds: u64,
@@ -10,6 +15,7 @@ pub struct Duration_type {
 }
 
 impl Duration_type {
+    /// Creates a new [`Duration_type`] from the specified number of seconds and nanoseconds.
     pub const fn New(Seconds: u64, Nanoseconds: u32) -> Self {
         Duration_type {
             Seconds,
@@ -17,10 +23,44 @@ impl Duration_type {
         }
     }
 
+    /// Returns the duration between the two instants.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// use Shared::Duration_type;
+    ///
+    /// let earlier = Duration_type::New(1, 0);
+    /// let later = Duration_type::New(2, 0);
+    ///
+    /// let duration = later.Get_duration_since(&earlier);
+    ///
+    /// assert_eq!(duration, Duration_type::New(1, 0));
+    ///
+    /// let duration = earlier.Get_duration_since(&later);
+    /// assert_eq!(duration, Duration_type::New(0, 0));
+    /// ```
     pub fn Get_duration_since(&self, Earlier: &Duration_type) -> Duration_type {
         self.Get_duration_since_checked(Earlier).unwrap_or_default()
     }
 
+    /// Returns the duration between the two instants, or `None` if the duration is negative.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    ///
+    /// use Shared::Duration_type;
+    ///
+    /// let earlier = Duration_type::New(1, 0);
+    /// let later = Duration_type::New(2, 0);
+    ///
+    /// let duration = later.Get_duration_since_checked(&earlier);
+    /// assert_eq!(duration, Some(Duration_type::New(1, 0)));
+    ///
+    /// let duration = earlier.Get_duration_since_checked(&later);
+    /// assert_eq!(duration, None);
+    /// ```
     pub fn Get_duration_since_checked(&self, Earlier: &Duration_type) -> Option<Duration_type> {
         let self_duration = Duration::new(self.Seconds, self.Nanoseconds);
         let earlier_duration = Duration::new(Earlier.Seconds, Earlier.Nanoseconds);
@@ -32,6 +72,22 @@ impl Duration_type {
             })
     }
 
+    /// Returns the duration between the two instants, saturating at the bounds of the type.
+    ///
+    /// # Example
+    ///
+    /// ```rust
+    /// use Shared::Duration_type;
+    ///
+    /// let earlier = Duration_type::New(1, 0);
+    /// let later = Duration_type::New(2, 0);
+    ///
+    /// let duration = later.Get_duration_since_saturating(&earlier);
+    /// assert_eq!(duration, Duration_type::New(1, 0));
+    ///
+    /// let duration = earlier.Get_duration_since_saturating(&later);
+    /// assert_eq!(duration, Duration_type::default());
+    /// ```
     pub fn Get_duration_since_saturating(&self, earlier: &Duration_type) -> Duration_type {
         let self_duration = Duration::new(self.Seconds, self.Nanoseconds);
         let earlier_duration = Duration::new(earlier.Seconds, earlier.Nanoseconds);
@@ -80,18 +136,59 @@ impl Duration_type {
         }
     }
 
+    /// Returns the number of seconds in the duration.
+    /// 
+    /// # Example
+    /// 
+    /// ```rust
+    /// use Shared::Duration_type;
+    /// 
+    /// let duration = Duration_type::New(1, 500_000_000);
+    /// assert_eq!(duration.As_seconds(), 1);
+    /// ```
     pub fn As_seconds(&self) -> u64 {
         self.Seconds
     }
 
+    /// Returns the number of milliseconds in the duration.
+    /// 
+    /// # Example
+    /// 
+    /// ```rust
+    /// use Shared::Duration_type;
+    /// 
+    /// let duration = Duration_type::New(1, 500_000_000);
+    /// assert_eq!(duration.As_milliseconds(), 1_500);
+    /// ```
     pub fn As_milliseconds(&self) -> u64 {
         self.As_microseconds() as u64 / 1_000
     }
 
+    /// Returns the number of microseconds in the duration.
+    /// 
+    /// # Example
+    /// 
+    /// ```rust
+    /// use Shared::Duration_type;
+    /// 
+    /// let duration = Duration_type::New(1, 500_000_000);
+    /// 
+    /// assert_eq!(duration.As_microseconds(), 1_500_000);
+    /// ```
     pub fn As_microseconds(&self) -> u128 {
         self.As_nanoseconds() / 1_000
     }
 
+    /// Returns the number of nanoseconds in the duration.
+    /// 
+    /// # Example
+    /// 
+    /// ```rust
+    /// use Shared::Duration_type;
+    /// 
+    /// let duration = Duration_type::New(1, 500_000_000);
+    /// assert_eq!(duration.As_nanoseconds(), 1_500_000_000);
+    /// ```
     pub fn As_nanoseconds(&self) -> u128 {
         u128::from(self.Seconds) * 1_000_000_000 + u128::from(self.Nanoseconds)
     }