Add doc comments to Mdf methods

Author: pitdicker

src/naive/internals.rs

@@ -130,6 +130,9 @@ impl fmt::Debug for YearFlags {
 const MAX_OL: u32 = 366 << 1; // `(366 << 1) | 1` would be day 366 in a non-leap year
 const MAX_MDL: u32 = (12 << 6) | (31 << 1) | 1;
 
+// The next table are adjustment values to convert a date encoded as month-day-leapyear to
+// ordinal-leapyear. OL = MDL - adjustment.
+// Dates that do not exist are encoded as `XX`.
 const XX: i8 = 0;
 const MDL_TO_OL: &[i8; MAX_MDL as usize + 1] = &[
     XX, XX, XX, XX, XX, XX, XX, XX, XX, XX, XX, XX, XX, XX, XX, XX, XX, XX, XX, XX, XX, XX, XX, XX,
@@ -229,6 +232,14 @@ const OL_TO_MDL: &[u8; MAX_OL as usize + 1] = &[
 pub(super) struct Mdf(u32);
 
 impl Mdf {
+    /// Makes a new `Mdf` value from month, day and `YearFlags`.
+    ///
+    /// This method doesn't fully validate the range of the `month` and `day` parameters, only as
+    /// much as what can't be deferred until later. The year `flags` are trusted to be correct.
+    ///
+    /// # Errors
+    ///
+    /// Returns `None` if `month > 12` or `day > 31`.
     #[inline]
     pub(super) const fn new(month: u32, day: u32, YearFlags(flags): YearFlags) -> Option<Mdf> {
         match month <= 12 && day <= 31 {
@@ -237,19 +248,29 @@ impl Mdf {
         }
     }
 
+    /// Makes a new `Mdf` value from an `i32` with an ordinal and a leap year flag, and year
+    /// `flags`.
+    ///
+    /// The `ol` is trusted to be valid, and the `flags` are trusted to match it.
     #[inline]
     pub(super) const fn from_ol(ol: i32, YearFlags(flags): YearFlags) -> Mdf {
         debug_assert!(ol > 1 && ol <= MAX_OL as i32);
         // Array is indexed from `[2..=MAX_OL]`, with a `0` index having a meaningless value.
         Mdf(((ol as u32 + OL_TO_MDL[ol as usize] as u32) << 3) | flags as u32)
     }
 
+    /// Returns the month of this `Mdf`.
     #[inline]
     pub(super) const fn month(&self) -> u32 {
         let Mdf(mdf) = *self;
         mdf >> 9
     }
 
+    /// Replaces the month of this `Mdf`, keeping the day and flags.
+    ///
+    /// # Errors
+    ///
+    /// Returns `None` if `month > 12`.
     #[inline]
     pub(super) const fn with_month(&self, month: u32) -> Option<Mdf> {
         if month > 12 {
@@ -260,12 +281,18 @@ impl Mdf {
         Some(Mdf((mdf & 0b1_1111_1111) | (month << 9)))
     }
 
+    /// Returns the day of this `Mdf`.
     #[inline]
     pub(super) const fn day(&self) -> u32 {
         let Mdf(mdf) = *self;
         (mdf >> 4) & 0b1_1111
     }
 
+    /// Replaces the day of this `Mdf`, keeping the month and flags.
+    ///
+    /// # Errors
+    ///
+    /// Returns `None` if `day > 31`.
     #[inline]
     pub(super) const fn with_day(&self, day: u32) -> Option<Mdf> {
         if day > 31 {
@@ -276,12 +303,22 @@ impl Mdf {
         Some(Mdf((mdf & !0b1_1111_0000) | (day << 4)))
     }
 
+    /// Replaces the flags of this `Mdf`, keeping the month and day.
     #[inline]
     pub(super) const fn with_flags(&self, YearFlags(flags): YearFlags) -> Mdf {
         let Mdf(mdf) = *self;
         Mdf((mdf & !0b1111) | flags as u32)
     }
 
+    /// Returns the ordinal that corresponds to this `Mdf`.
+    ///
+    /// This does a table lookup to calculate the corresponding ordinal. It will return an error if
+    /// the `Mdl` turns out not to be a valid date.
+    ///
+    /// # Errors
+    ///
+    /// Returns `None` if `month == 0` or `day == 0`, or if a the given day does not exist in the
+    /// given month.
     #[inline]
     pub(super) const fn ordinal(&self) -> Option<u32> {
         let mdl = self.0 >> 3;
@@ -291,11 +328,21 @@ impl Mdf {
         }
     }
 
+    /// Returns the year flags of this `Mdf`.
     #[inline]
     pub(super) const fn year_flags(&self) -> YearFlags {
         YearFlags((self.0 & 0b1111) as u8)
     }
 
+    /// Returns the ordinal that corresponds to this `Mdf`, encoded as a value including year flags.
+    ///
+    /// This does a table lookup to calculate the corresponding ordinal. It will return an error if
+    /// the `Mdl` turns out not to be a valid date.
+    ///
+    /// # Errors
+    ///
+    /// Returns `None` if `month == 0` or `day == 0`, or if a the given day does not exist in the
+    /// given month.
     #[inline]
     pub(super) const fn ordinal_and_flags(&self) -> Option<i32> {
         let mdl = self.0 >> 3;