From 6f41a77a252eb221a0d11bec16c28a0520c92311 Mon Sep 17 00:00:00 2001
From: Nate Butler <iamnbutler@gmail.com>
Date: Thu, 2 Nov 2023 11:53:20 -0400
Subject: [PATCH] Document format_distance

Adds docs for:
- distance_in_seconds
- distance_string
- naive_format_distance
- naive_format_distance_from_now
---
 crates/ui2/src/utils/format_distance.rs | 58 +++++++++++++++++++++++++
 1 file changed, 58 insertions(+)

diff --git a/crates/ui2/src/utils/format_distance.rs b/crates/ui2/src/utils/format_distance.rs
index 8a33619910..133eabc202 100644
--- a/crates/ui2/src/utils/format_distance.rs
+++ b/crates/ui2/src/utils/format_distance.rs
@@ -1,10 +1,18 @@
 use chrono::NaiveDateTime;
 
+/// Calculates the distance in seconds between two NaiveDateTime objects.
+/// It returns a signed integer denoting the difference. If `date` is earlier than `base_date`, the returned value will be negative.
+///
+/// ## Arguments
+///
+/// * `date` - A NaiveDateTime object representing the date of interest
+/// * `base_date` - A NaiveDateTime object representing the base date against which the comparison is made
 fn distance_in_seconds(date: NaiveDateTime, base_date: NaiveDateTime) -> i64 {
     let duration = date.signed_duration_since(base_date);
     -duration.num_seconds()
 }
 
+/// Generates a string describing the time distance between two dates in a human-readable way.
 fn distance_string(distance: i64, include_seconds: bool, add_suffix: bool) -> String {
     let suffix = if distance < 0 { " from now" } else { " ago" };
 
@@ -74,6 +82,33 @@ fn distance_string(distance: i64, include_seconds: bool, add_suffix: bool) -> St
     }
 }
 
+/// Get the time difference between two dates into a relative human readable string.
+///
+/// For example, "less than a minute ago", "about 2 hours ago", "3 months from now", etc.
+///
+/// Use [naive_format_distance_from_now] to compare a NaiveDateTime against now.
+///
+/// # Arguments
+///
+/// * `date` - The NaiveDateTime to compare.
+/// * `base_date` - The NaiveDateTime to compare against.
+/// * `include_seconds` - A boolean. If true, distances less than a minute are more detailed
+/// * `add_suffix` - A boolean. If true, result indicates if the time is in the past or future
+///
+/// # Example
+///
+/// ```rust
+/// use chrono::DateTime;
+/// use ui2::utils::naive_format_distance;
+///
+/// fn time_between_moon_landings() -> String {
+///     let date = DateTime::parse_from_rfc3339("1969-07-20T00:00:00Z").unwrap().naive_local();
+///     let base_date = DateTime::parse_from_rfc3339("1972-12-14T00:00:00Z").unwrap().naive_local();
+///     format!("There was {} between the first and last crewed moon landings.", naive_format_distance(date, base_date, false, false))
+/// }
+/// ```
+///
+/// Output: `"There was about 3 years between the first and last crewed moon landings."`
 pub fn naive_format_distance(
     date: NaiveDateTime,
     base_date: NaiveDateTime,
@@ -85,6 +120,29 @@ pub fn naive_format_distance(
     distance_string(distance, include_seconds, add_suffix)
 }
 
+/// Get the time difference between a date and now as relative human readable string.
+///
+/// For example, "less than a minute ago", "about 2 hours ago", "3 months from now", etc.
+///
+/// # Arguments
+///
+/// * `datetime` - The NaiveDateTime to compare with the current time.
+/// * `include_seconds` - A boolean. If true, distances less than a minute are more detailed
+/// * `add_suffix` - A boolean. If true, result indicates if the time is in the past or future
+///
+/// # Example
+///
+/// ```rust
+/// use chrono::DateTime;
+/// use ui2::utils::naive_format_distance_from_now;
+///
+/// fn time_since_first_moon_landing() -> String {
+///     let date = DateTime::parse_from_rfc3339("1969-07-20T00:00:00Z").unwrap().naive_local();
+///     format!("It's been {} since Apollo 11 first landed on the moon.", naive_format_distance_from_now(date, false, false))
+/// }
+/// ```
+///
+/// Output: `It's been over 54 years since Apollo 11 first landed on the moon.`
 pub fn naive_format_distance_from_now(
     datetime: NaiveDateTime,
     include_seconds: bool,