From 22a0cf6938c866b9c08fe42b1321582d4e85ebe6 Mon Sep 17 00:00:00 2001
From: "Christoph J. Scherr" <Christoph.Scherr@newtec.de>
Date: Mon, 4 Mar 2024 17:08:16 +0100
Subject: [PATCH] modes documentations, make format_duration public

also added a doc test for format_duration
---
 clock-tui/src/app/modes.rs | 32 +++++++++++++++++++++++++++++---
 1 file changed, 29 insertions(+), 3 deletions(-)

diff --git a/clock-tui/src/app/modes.rs b/clock-tui/src/app/modes.rs
index 16a4a8e..9ffae54 100644
--- a/clock-tui/src/app/modes.rs
+++ b/clock-tui/src/app/modes.rs
@@ -20,15 +20,40 @@ use tui::{
     widgets::{Paragraph, Widget},
 };
 
-#[derive(Copy, Clone)]
-pub(crate) enum DurationFormat {
+/// Describes how a [`Duration`] should be displayed.
+///
+/// For now, the only difference is if the deciseconds should be shown or not.
+#[derive(Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Debug, Hash)]
+pub enum DurationFormat {
     /// Hours, minutes, seconds, deciseconds
     HourMinSecDeci,
     /// Hours, minutes, seconds
     HourMinSec,
 }
 
-fn format_duration(duration: Duration, format: DurationFormat) -> String {
+/// Format a Duration, converting it into a String
+///
+/// The formatting can be configured with the [`DurationFormat`] passed into the function.
+///
+///
+/// ## Examples
+///
+/// ```
+/// use chrono::Duration;
+/// # use clock_tui::app::modes::*;
+/// # fn main() {
+/// let time = Duration::seconds(5555);
+/// let formatted_time = format_duration(time, DurationFormat::HourMinSecDeci);
+/// assert_eq!("1:32:35.0", &formatted_time);
+/// let formatted_time = format_duration(time, DurationFormat::HourMinSec);
+/// assert_eq!("1:32:35", &formatted_time);
+///
+/// let time = Duration::days(255);
+/// let formatted_time = format_duration(time, DurationFormat::HourMinSec);
+/// assert_eq!("255:00:00:00", &formatted_time);
+/// # }
+/// ```
+pub fn format_duration(duration: Duration, format: DurationFormat) -> String {
     let is_neg = duration < Duration::zero();
     let duration = if is_neg { -duration } else { duration };
 
@@ -57,6 +82,7 @@ fn format_duration(duration: Duration, format: DurationFormat) -> String {
     append_number(&mut result, minutes % 60);
     result.push(':');
 
+    // prepend a - if the duration is negative
     if is_neg {
         result.insert(0, '-');
     }