Improve neo marker docs (#5247)

components/datetime/src/neo_marker.rs

@@ -1187,7 +1187,7 @@ macro_rules! impl_date_marker {
         input_day_of_year = $day_of_year_yesno:ident,
         input_any_calendar_kind = $any_calendar_kind_yesno:ident,
     ) => {
-        #[doc = concat!("Marker for ", $description, ": ", $expectation)]
+        #[doc = concat!("**“", $expectation, "**” ⇒ ", $description)]
         ///
         /// # Examples
         ///
@@ -1340,7 +1340,7 @@ macro_rules! impl_time_marker {
         input_second = $second_yesno:ident,
         input_nanosecond = $nanosecond_yesno:ident,
     ) => {
-        #[doc = concat!("Marker for ", $description, ": ", $expectation)]
+        #[doc = concat!("**“", $expectation, "**” ⇒ ", $description)]
         ///
         /// # Examples
         ///
@@ -1445,7 +1445,7 @@ macro_rules! impl_zone_marker {
         zone_specific_long = $zone_specific_long_yesno:ident,
         zone_specific_short = $zone_specific_short_yesno:ident,
     ) => {
-        #[doc = concat!("Marker for ", $description, ": ", $expectation)]
+        #[doc = concat!("**“", $expectation, "**” ⇒ ", $description)]
         ///
         /// # Examples
         ///
@@ -1562,7 +1562,7 @@ macro_rules! impl_datetime_marker {
         date = $date:path,
         time = $time:path,
     ) => {
-        #[doc = concat!("Marker for ", $description, ": ", $expectation)]
+        #[doc = concat!("**“", $expectation, "**” ⇒ ", $description)]
         ///
         /// # Examples
         ///
@@ -1625,7 +1625,7 @@ macro_rules! impl_zoneddatetime_marker {
         time = $time:path,
         zone = $zone:path,
     ) => {
-        #[doc = concat!("Marker for ", $description, ": ", $expectation)]
+        #[doc = concat!("**“", $expectation, "**” ⇒ ", $description)]
         ///
         /// # Examples
         ///
@@ -1692,7 +1692,7 @@ macro_rules! impl_zoneddatetime_marker {
 impl_day_marker!(
     NeoYearMonthDayMarker,
     NeoDayComponents::YearMonthDay,
-    description = "a Year/Month/Day format",
+    description = "year, month, and day (era elided when possible)",
     expectation = "May 17, 2024",
     years = yes,
     months = yes,
@@ -1709,7 +1709,7 @@ impl_day_marker!(
 impl_day_marker!(
     NeoEraYearMonthMarker,
     NeoDayComponents::EraYearMonthDay,
-    description = "an Era/Year/Month/Day format",
+    description = "year, month, and day (era always displayed)",
     expectation = "May 17, 2024 AD",
     years = yes,
     months = yes,
@@ -1766,7 +1766,7 @@ impl_datetime_marker!(
 impl_date_marker!(
     NeoYearMonthMarker,
     NeoDateComponents::YearMonth,
-    description = "a Year/Month format",
+    description = "year and month (era elided when possible)",
     expectation = "May 2024",
     years = yes,
     months = yes,
@@ -1783,7 +1783,7 @@ impl_date_marker!(
 impl_zone_marker!(
     NeoTimeZoneSpecificMarker,
     NeoTimeZoneSkeleton::specific(),
-    description = "a specific time zone format with inherited length",
+    description = "specific time zone with inherited length, or GMT offset if unavailable",
     expectation = "CDT",
     needs_length_option = yes,
     zone_essentials = yes,
@@ -1829,7 +1829,7 @@ impl_zone_marker!(
     /// ```
     NeoTimeZoneSpecificShortMarker,
     NeoTimeZoneSkeleton::specific_short(),
-    description = "a short specific time zone format",
+    description = "specific time zone with a shorter length, or GMT offset if unavailable",
     expectation = "CDT",
     needs_length_option = no,
     zone_essentials = yes,
@@ -1843,7 +1843,7 @@ impl_zone_marker!(
 impl_zone_marker!(
     NeoTimeZoneSpecificLongMarker,
     NeoTimeZoneSkeleton::specific_long(),
-    description = "a long specific time zone format",
+    description = "specific time zone with a longer length, or GMT offset if unavailable",
     expectation = "Central Daylight Time",
     needs_length_option = no,
     zone_essentials = yes,
@@ -1857,7 +1857,7 @@ impl_zone_marker!(
 impl_zone_marker!(
     NeoTimeZoneGmtMarker,
     NeoTimeZoneSkeleton::gmt(),
-    description = "a GMT-offset time zone format with inherited length",
+    description = "GMT offset with inherited length",
     expectation = "GMT-05:00", // TODO: Implement short localized GMT
     needs_length_option = yes,
     zone_essentials = yes,
@@ -1871,7 +1871,7 @@ impl_zone_marker!(
 impl_zone_marker!(
     NeoTimeZoneGmtShortMarker,
     NeoTimeZoneSkeleton::gmt_short(),
-    description = "a GMT-offset short time zone format",
+    description = "GMT offset with a shorter length",
     expectation = "GMT-05:00", // TODO: Implement short localized GMT
     needs_length_option = no,
     zone_essentials = yes,
@@ -1885,7 +1885,7 @@ impl_zone_marker!(
 impl_zone_marker!(
     NeoTimeZoneGmtLongMarker,
     NeoTimeZoneSkeleton::gmt_long(),
-    description = "a GMT-offset long time zone format",
+    description = "GMT offset with a longer length",
     expectation = "GMT-05:00",
     needs_length_option = no,
     zone_essentials = yes,
@@ -1899,7 +1899,7 @@ impl_zone_marker!(
 impl_zone_marker!(
     NeoTimeZoneGenericMarker,
     NeoTimeZoneSkeleton::generic(),
-    description = "a generic time zone format with inherited length",
+    description = "generic time zone with inherited length, or location if unavailable",
     expectation = "CT",
     needs_length_option = yes,
     zone_essentials = yes,
@@ -1945,7 +1945,7 @@ impl_zone_marker!(
     /// ```
     NeoTimeZoneGenericShortMarker,
     NeoTimeZoneSkeleton::generic_short(),
-    description = "a generic short time zone format",
+    description = "generic time zone with a shorter length, or location if unavailable",
     expectation = "CT",
     needs_length_option = no,
     zone_essentials = yes,
@@ -1959,7 +1959,7 @@ impl_zone_marker!(
 impl_zone_marker!(
     NeoTimeZoneGenericLongMarker,
     NeoTimeZoneSkeleton::generic_long(),
-    description = "a generic long time zone format",
+    description = "generic time zone with a longer length, or location if unavailable",
     expectation = "Central Time",
     needs_length_option = no,
     zone_essentials = yes,
@@ -1973,7 +1973,7 @@ impl_zone_marker!(
 impl_zone_marker!(
     NeoTimeZoneLocationMarker,
     NeoTimeZoneSkeleton::location(),
-    description = "a location time zone format",
+    description = "location time zone",
     expectation = "Chicago Time",
     needs_length_option = no,
     zone_essentials = yes,