From b1399d193fcb20c09457a1f22c5c1dd8009c84b1 Mon Sep 17 00:00:00 2001
From: "Tobin C. Harding" <me@tobin.cc>
Date: Wed, 18 Dec 2024 11:26:14 +1100
Subject: [PATCH] units: Improve rustdocs on macros

Extensively document the two _real_ public macros (not the helpers) in
`units::parse`.
---
 units/src/parse.rs | 48 ++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 44 insertions(+), 4 deletions(-)

diff --git a/units/src/parse.rs b/units/src/parse.rs
index 35c880f37..ec927716f 100644
--- a/units/src/parse.rs
+++ b/units/src/parse.rs
@@ -91,10 +91,30 @@ pub fn int<T: Integer, S: AsRef<str> + Into<InputString>>(s: S) -> Result<T, Par
     })
 }
 
-/// Implements `FromStr` and `TryFrom<{&str, String, Box<str>}> for $to` using `parse::int`, mapping
-/// the output using infallible conversion function `fn`.
+/// Implements standard parsing traits for `$type` by calling `parse::int`.
 ///
-/// The `Error` type is `ParseIntError`
+/// Once the string is converted to an integer the infallible conversion function `fn` is used to
+/// create the type `to`.
+///
+/// Implements:
+///
+/// * `FromStr`
+/// * `TryFrom<&str>`
+///
+/// And if `alloc` feature is enabled in calling crate:
+///
+/// * `TryFrom<Box<str>>`
+/// * `TryFrom<String>`
+///
+/// # Arguments
+///
+/// * `to` - the type converted to e.g., `impl From<&str> for $to`.
+/// * `err` - the error type returned by `$inner_fn` (implies returned by `FromStr` and `TryFrom`).
+/// * `fn`: The infallible conversion function to call to convert from an integer.
+///
+/// # Errors
+///
+/// If parsing the string fails then a `units::parse::ParseIntError` is returned.
 #[macro_export]
 macro_rules! impl_parse_str_from_int_infallible {
     ($to:ident, $inner:ident, $fn:ident) => {
@@ -131,7 +151,27 @@ macro_rules! impl_tryfrom_str_from_int_infallible {
     }
 }
 
-/// Implements standard parsing traits for `$type` by calling into `$inner_fn`.
+/// Implements standard parsing traits for `$type` by calling through to `$inner_fn`.
+///
+/// Implements:
+///
+/// * `FromStr`
+/// * `TryFrom<&str>`
+///
+/// And if `alloc` feature is enabled in calling crate:
+///
+/// * `TryFrom<Box<str>>`
+/// * `TryFrom<String>`
+///
+/// # Arguments
+///
+/// * `to` - the type converted to e.g., `impl From<&str> for $to`.
+/// * `err` - the error type returned by `$inner_fn` (implies returned by `FromStr` and `TryFrom`).
+/// * `inner_fn`: The fallible conversion function to call to convert from a string reference.
+///
+/// # Errors
+///
+/// All functions use the error returned by `$inner_fn`.
 #[macro_export]
 macro_rules! impl_parse_str {
     ($to:ty, $err:ty, $inner_fn:expr) => {