Fix DynamicSpacing docs (#20509)

Nate Butler created 1 year ago

In #20504 the CustomSpacing enum variants ended up not having docs. This
PR fixes that, now docs correctly show for variants.


https://github.com/user-attachments/assets/8cc409c9-7b71-4c21-a538-3fd5dded3e00

Release Notes:

- N/A

Change summary

crates/ui/src/styles/spacing.rs         | 23 ++++++++++++++++
crates/ui_macros/src/dynamic_spacing.rs | 38 ++++++++++++++------------
2 files changed, 44 insertions(+), 17 deletions(-)

Detailed changes

crates/ui/src/styles/spacing.rs

@@ -4,6 +4,29 @@ use theme::{ThemeSettings, UiDensity};
 use ui_macros::derive_dynamic_spacing;
 
 // Derives [DynamicSpacing]. See [ui_macros::derive_dynamic_spacing].
+//
+// There are 3 UI density settings: Compact, Default, and Comfortable.
+//
+// When a tuple of three values is provided, the values are used directly.
+//
+// Example: (1, 2, 4) => Compact: 1px, Default: 2px, Comfortable: 4px
+//
+// When a single value is provided, the standard spacing formula is
+// used to derive the of spacing values. This formula can be found in
+// the macro.
+//
+// Example:
+//
+// Assuming the standard formula is (n-4, n, n+4)
+//
+// 24 => Compact: 20px, Default: 24px, Comfortable: 28px
+//
+// The [DynamicSpacing] enum variants use a BaseXX format,
+// where XX = the pixel value @ default rem size and the default UI density.
+//
+// Example:
+//
+// DynamicSpacing::Base16 would return 16px at the default UI scale & density.
 derive_dynamic_spacing![
     (0, 0, 0),
     (1, 1, 2),

crates/ui_macros/src/dynamic_spacing.rs

@@ -88,37 +88,41 @@ pub fn derive_spacing(input: TokenStream) -> TokenStream {
         })
         .collect();
 
-    let variant_docs: Vec<_> = input
+    let (variant_names, doc_strings): (Vec<_>, Vec<_>) = input
         .values
         .iter()
         .map(|v| {
             let variant = match v {
-                DynamicSpacingValue::Single(n) => format_ident!("Base{:02}", n.base10_parse::<u32>().unwrap()),
-                DynamicSpacingValue::Tuple(_, b, _) => format_ident!("Base{:02}", b.base10_parse::<u32>().unwrap()),
+                DynamicSpacingValue::Single(n) => {
+                    format_ident!("Base{:02}", n.base10_parse::<u32>().unwrap())
+                }
+                DynamicSpacingValue::Tuple(_, b, _) => {
+                    format_ident!("Base{:02}", b.base10_parse::<u32>().unwrap())
+                }
             };
-            match v {
+            let doc_string = match v {
                 DynamicSpacingValue::Single(n) => {
-                    // When a single value is passed in, derive the compact and comfortable values.
                     let n = n.base10_parse::<f32>().unwrap();
                     let compact = (n - 4.0).max(0.0);
                     let comfortable = n + 4.0;
-                    quote! {
-                        #[doc = concat!("@16px/rem: `", stringify!(#compact), "px`|`", stringify!(#n), "px`|`", stringify!(#comfortable), "px` - Scales with the user's rem size.")]
-                        #variant,
-                    }
+                    format!(
+                        "`{}px`|`{}px`|`{}px (@16px/rem)` - Scales with the user's rem size.",
+                        compact, n, comfortable
+                    )
                 }
                 DynamicSpacingValue::Tuple(a, b, c) => {
                     let a = a.base10_parse::<f32>().unwrap();
                     let b = b.base10_parse::<f32>().unwrap();
                     let c = c.base10_parse::<f32>().unwrap();
-                    quote! {
-                        #[doc = concat!("@16px/rem: `", stringify!(#a), "px`|`", stringify!(#b), "px`|`", stringify!(#c), "px` - Scales with the user's rem size.")]
-                        #variant,
-                    }
+                    format!(
+                        "`{}px`|`{}px`|`{}px (@16px/rem)` - Scales with the user's rem size.",
+                        a, b, c
+                    )
                 }
-            }
+            };
+            (quote!(#variant), quote!(#doc_string))
         })
-        .collect();
+        .unzip();
 
     let expanded = quote! {
         /// A dynamic spacing system that adjusts spacing based on
@@ -132,8 +136,8 @@ pub fn derive_spacing(input: TokenStream) -> TokenStream {
         #[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
         pub enum DynamicSpacing {
             #(
-                #[doc = stringify!(#variant_docs)]
-                #variant_docs
+                #[doc = #doc_strings]
+                #variant_names,
             )*
         }