docs(datetime): update & expand week-of docstrings

components/datetime/src/date.rs

@@ -167,10 +167,12 @@ fn week_of_year<T: DateInput>(
 
 /// Returns the week of month according to a calendar with min_week_days = 1.
 ///
-/// This is different from what the UTS35 spec describes but the latter is
+/// This is different from what the UTS35 spec describes [1] but the latter is
 /// missing a month of week-of-month field so following the spec would result
 /// in inconsistencies (e.g. in the ISO calendar 2021-01-01 is the last week
 /// of December but 'MMMMW' would have it formatted as 'week 5 of January').
+///
+/// 1: https://www.unicode.org/reports/tr35/tr35-55/tr35-dates.html#Date_Patterns_Week_Of_Year
 fn week_of_month<T: DateInput>(
     datetime: &T,
     first_weekday: IsoWeekday,

components/datetime/src/options/components.rs

@@ -93,7 +93,7 @@ pub struct Bag {
     pub year: Option<Year>,
     /// Include the month, such as "April" or "Apr".
     pub month: Option<Month>,
-    /// Include the week, such as "1st" or "1".
+    /// Include the week number, such as "51st" or "51" for week 51.
     pub week: Option<Week>,
     /// Include the day, such as "07" or "7".
     pub day: Option<Numeric>,
@@ -398,20 +398,22 @@ pub enum Month {
 
 // Each enum variant is documented with the UTS 35 field information from:
 // https://unicode.org/reports/tr35/tr35-dates.html#Date_Field_Symbol_Table
-//
-/// Options for displaying the current week for the `components::`[`Bag`].
+
+/// Options for displaying the current week number for the `components::`[`Bag`].
+///
+/// Week numbers are relative to either a month or year, e.g. 'week 3 of January' or 'week 40 of 2000'.
 #[derive(Debug, Clone, Copy, PartialEq)]
 #[cfg_attr(
     feature = "serde",
     derive(Serialize, Deserialize),
     serde(rename_all = "kebab-case")
 )]
 pub enum Week {
-    /// The week of the month, such as "3".
+    /// The week of the month, such as the "3" in "week 3 of January".
     WeekOfMonth,
-    /// The numeric value of the week of the year, such as "8".
+    /// The numeric value of the week of the year, such as the "8" in "week 8 of 2000".
     NumericWeekOfYear,
-    /// The two-digit value of the week of the year, such as "08".
+    /// The two-digit value of the week of the year, such as the "08" in "2000-W08".
     TwoDigitWeekOfYear,
 }