modes documentations, make format_duration public

also added a doc test for format_duration

clock-tui/src/app/modes.rs

@@ -20,15 +20,40 @@ use tui::{
     widgets::{Paragraph, Widget},
 };
 
-#[derive(Copy, Clone)]
+/// Describes how a [`Duration`] should be displayed.
-pub(crate) enum DurationFormat {
+///
+/// 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, '-');
     }