Skip to content

Commit

Permalink
Improved documentation formatting
Browse files Browse the repository at this point in the history 
  - Made all Rustdoc types into links, not just the first mention.

  - General formatting improvements.
  • Loading branch information
@danwilliams
danwilliams committed Oct 7, 2023
1 parent da886da commit 3ea91ba
Show file tree
Hide file tree
Showing 6 changed files with 281 additions and 160 deletions.
4 changes: 2 additions & 2 deletions crates/rubedo-macros/src/lib.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@ use std::net::IpAddr;
///
/// Note that this macro will panic if it fails to parse a string literal as an
/// IP address. This is by design, so that all variants of IP creation return an
/// `IpAddr` instance, just like [`IpAddr::from()`]. This macro is intended to
/// [`IpAddr`] instance, just like [`IpAddr::from()`]. This macro is intended to
/// be used with hard-coded addresses. If you need to handle errors, use the
/// standard [`IpAddr::from_str()`](IpAddr) method instead.
///
Expand All @@ -47,7 +47,7 @@ use std::net::IpAddr;
/// assert_eq!(ip!(1, 2, 3, 4), IpAddr::from([1, 2, 3, 4]));
/// ```
///
/// # See Also
/// # See also
///
/// * [`IpAddr`]
///
Expand Down
118 changes: 109 additions & 9 deletions crates/rubedo/src/chrono.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -34,11 +34,12 @@ pub trait DurationExt {
];

// humanize
/// Returns a human-readable string representation of the duration.
/// Returns a human-readable string representation of a [`Duration`].
///
/// This will indicate the duration as an expression of the largest unit
/// This will indicate the [`Duration`] as an expression of the largest unit
/// available. For example, if the duration is 1 year, 2 months, 3 weeks,
/// 4 days, 5 hours, 6 minutes, and 7 seconds, it will return "1 year".
///
fn humanize(&self) -> String;
}

Expand All @@ -64,13 +65,20 @@ pub trait NaiveDateExt {
///
/// Although this is a static method, it does not return an [`Option`] as it
/// cannot fail.
///
fn today() -> NaiveDate;

// days_in_month
/// Returns the number of days in the date's month.
///
/// This method operates on `&self`. For the equivalent method that operates
/// without an instance, see [`days_in_month_opt()`](NaiveDateExt::days_in_month_opt()).
///
/// # See also
///
/// * [`days_in_month_opt()`](NaiveDateExt::days_in_month_opt())
/// * [`days_in_year()`](NaiveDateExt::days_in_year())
///
fn days_in_month(&self) -> u32;

// days_in_month_opt
Expand All @@ -80,14 +88,26 @@ pub trait NaiveDateExt {
/// operates on `&self`, see [`days_in_month()`](NaiveDateExt::days_in_month()).
///
/// The outcome is wrapped in an [`Option`]. If the given year or month is
/// invalid, `None` is returned.
/// invalid, [`None`] is returned.
///
/// # See also
///
/// * [`days_in_month()`](NaiveDateExt::days_in_month())
/// * [`days_in_year_opt()`](NaiveDateExt::days_in_year_opt())
///
fn days_in_month_opt(year: i32, month: u32) -> Option<u32>;

// days_in_year
/// Returns the number of days in the date's year.
///
/// This method operates on `&self`. For the equivalent method that operates
/// without an instance, see [`days_in_year_opt()`](NaiveDateExt::days_in_year_opt()).
///
/// # See also
///
/// * [`days_in_month()`](NaiveDateExt::days_in_month())
/// * [`days_in_year_opt()`](NaiveDateExt::days_in_year_opt())
///
fn days_in_year(&self) -> u32;

// days_in_year_opt
Expand All @@ -97,14 +117,25 @@ pub trait NaiveDateExt {
/// operates on `&self`, see [`days_in_year()`](NaiveDateExt::days_in_year()).
///
/// The outcome is wrapped in an [`Option`]. If the given year is invalid,
/// `None` is returned.
/// [`None`] is returned.
///
/// # See also
///
/// * [`days_in_month_opt()`](NaiveDateExt::days_in_month_opt())
/// * [`days_in_year()`](NaiveDateExt::days_in_year())
///
fn days_in_year_opt(year: i32) -> Option<u32>;

// is_leap_year
/// Returns `true` if the date's year is a leap year.
///
/// This method operates on `&self`. For the equivalent method that operates
/// without an instance, see [`is_leap_year_opt()`](NaiveDateExt::is_leap_year_opt()).
///
/// # See also
///
/// * [`is_leap_year_opt()`](NaiveDateExt::is_leap_year_opt())
///
fn is_leap_year(&self) -> bool;

// is_leap_year_opt
Expand All @@ -114,14 +145,27 @@ pub trait NaiveDateExt {
/// operates on `&self`, see [`is_leap_year()`](NaiveDateExt::is_leap_year()).
///
/// The outcome is wrapped in an [`Option`]. If the given year is invalid,
/// `None` is returned.
/// [`None`] is returned.
///
/// # See also
///
/// * [`is_leap_year()`](NaiveDateExt::is_leap_year())
///
fn is_leap_year_opt(year: i32) -> Option<bool>;

// start_of_month
/// Returns the date of the first day of the date's month.
///
/// This method operates on `&self`. For the equivalent method that operates
/// without an instance, see [`start_of_month_opt()`](NaiveDateExt::start_of_month_opt()).
///
/// # See also
///
/// * [`end_of_month()`](NaiveDateExt::end_of_month())
/// * [`end_of_year()`](NaiveDateExt::end_of_year())
/// * [`start_of_month_opt()`](NaiveDateExt::start_of_month_opt())
/// * [`start_of_year()`](NaiveDateExt::start_of_year())
///
fn start_of_month(&self) -> NaiveDate;

// start_of_month_opt
Expand All @@ -131,14 +175,30 @@ pub trait NaiveDateExt {
/// operates on `&self`, see [`start_of_month()`](NaiveDateExt::start_of_month()).
///
/// The outcome is wrapped in an [`Option`]. If the given year or month is
/// invalid, `None` is returned.
/// invalid, [`None`] is returned.
///
/// # See also
///
/// * [`end_of_month_opt()`](NaiveDateExt::end_of_month_opt())
/// * [`end_of_year_opt()`](NaiveDateExt::end_of_year_opt())
/// * [`start_of_month()`](NaiveDateExt::start_of_month())
/// * [`start_of_year_opt()`](NaiveDateExt::start_of_year_opt())
///
fn start_of_month_opt(year: i32, month: u32) -> Option<NaiveDate>;

// end_of_month
/// Returns the date of the last day of the date's month.
///
/// This method operates on `&self`. For the equivalent method that operates
/// without an instance, see [`end_of_month_opt()`](NaiveDateExt::end_of_month_opt()).
///
/// # See also
///
/// * [`end_of_month_opt()`](NaiveDateExt::end_of_month_opt())
/// * [`end_of_year()`](NaiveDateExt::end_of_year())
/// * [`start_of_month()`](NaiveDateExt::start_of_month())
/// * [`start_of_year()`](NaiveDateExt::start_of_year())
///
fn end_of_month(&self) -> NaiveDate;

// end_of_month_opt
Expand All @@ -148,14 +208,30 @@ pub trait NaiveDateExt {
/// operates on `&self`, see [`end_of_month()`](NaiveDateExt::end_of_month()).
///
/// The outcome is wrapped in an [`Option`]. If the given year or month is
/// invalid, `None` is returned.
/// invalid, [`None`] is returned.
///
/// # See also
///
/// * [`end_of_month()`](NaiveDateExt::end_of_month())
/// * [`end_of_year_opt()`](NaiveDateExt::end_of_year_opt())
/// * [`start_of_month_opt()`](NaiveDateExt::start_of_month_opt())
/// * [`start_of_year_opt()`](NaiveDateExt::start_of_year_opt())
///
fn end_of_month_opt(year: i32, month: u32) -> Option<NaiveDate>;

// start_of_year
/// Returns the date of the first day of the date's year.
///
/// This method operates on `&self`. For the equivalent method that operates
/// without an instance, see [`start_of_year_opt()`](NaiveDateExt::start_of_year_opt()).
///
/// # See also
///
/// * [`end_of_month()`](NaiveDateExt::end_of_month())
/// * [`end_of_year()`](NaiveDateExt::end_of_year())
/// * [`start_of_month()`](NaiveDateExt::start_of_month())
/// * [`start_of_year_opt()`](NaiveDateExt::start_of_year_opt())
///
fn start_of_year(&self) -> NaiveDate;

// start_of_year_opt
Expand All @@ -165,14 +241,30 @@ pub trait NaiveDateExt {
/// operates on `&self`, see [`start_of_year()`](NaiveDateExt::start_of_year()).
///
/// The outcome is wrapped in an [`Option`]. If the given year is invalid,
/// `None` is returned.
/// [`None`] is returned.
///
/// # See also
///
/// * [`end_of_month_opt()`](NaiveDateExt::end_of_month_opt())
/// * [`end_of_year_opt()`](NaiveDateExt::end_of_year_opt())
/// * [`start_of_month_opt()`](NaiveDateExt::start_of_month_opt())
/// * [`start_of_year()`](NaiveDateExt::start_of_year())
///
fn start_of_year_opt(year: i32) -> Option<NaiveDate>;

// end_of_year
/// Returns the date of the last day of the date's year.
///
/// This method operates on `&self`. For the equivalent method that operates
/// without an instance, see [`end_of_year_opt()`](NaiveDateExt::end_of_year_opt()).
///
/// # See also
///
/// * [`end_of_month()`](NaiveDateExt::end_of_month())
/// * [`end_of_year_opt()`](NaiveDateExt::end_of_year_opt())
/// * [`start_of_month()`](NaiveDateExt::start_of_month())
/// * [`start_of_year()`](NaiveDateExt::start_of_year())
///
fn end_of_year(&self) -> NaiveDate;

// end_of_year_opt
Expand All @@ -182,7 +274,15 @@ pub trait NaiveDateExt {
/// operates on `&self`, see [`end_of_year()`](NaiveDateExt::end_of_year()).
///
/// The outcome is wrapped in an [`Option`]. If the given year is invalid,
/// `None` is returned.
/// [`None`] is returned.
///
/// # See also
///
/// * [`end_of_month_opt()`](NaiveDateExt::end_of_month_opt())
/// * [`end_of_year()`](NaiveDateExt::end_of_year())
/// * [`start_of_month_opt()`](NaiveDateExt::start_of_month_opt())
/// * [`start_of_year_opt()`](NaiveDateExt::start_of_year_opt())
///
fn end_of_year_opt(year: i32) -> Option<NaiveDate>;
}

Expand Down
Loading

0 comments on commit 3ea91ba

Please sign in to comment.