Fix and add to ISO Parser docs

boa_engine/src/builtins/temporal/duration/mod.rs

@@ -828,7 +828,7 @@ impl Duration {
         Ok((whole + remainder).into())
     }
 
-    /// 7.3.22 Temporal.Duration.prototype.toString ( [ options ] )
+    /// 7.3.22 `Temporal.Duration.prototype.toString ( [ options ] )`
     pub(crate) fn to_string(
         this: &JsValue,
         _: &[JsValue],
@@ -839,7 +839,7 @@ impl Duration {
             .into())
     }
 
-    /// 7.3.23 Temporal.Duration.prototype.toJSON ( )
+    /// 7.3.23 `Temporal.Duration.prototype.toJSON ( )`
     pub(crate) fn to_json(this: &JsValue, _: &[JsValue], _: &mut Context<'_>) -> JsResult<JsValue> {
         Err(JsNativeError::range()
             .with_message("not yet implemented.")

boa_engine/src/builtins/temporal/plain_date/iso.rs

@@ -34,7 +34,7 @@ impl IsoDateRecord {
 
 impl IsoDateRecord {
     // TODO: look into using Date<Iso> across the board...TBD.
-    /// Creates `[[ISOYear]]`, `[[isoMonth]]`, `[[isoDay]]` fields from `ICU4X`'s Date<Iso> struct.
+    /// Creates `[[ISOYear]]`, `[[isoMonth]]`, `[[isoDay]]` fields from `ICU4X`'s `Date<Iso>` struct.
     pub(crate) fn from_date_iso(date: Date<Iso>) -> Self {
         Self {
             year: date.year().number,
@@ -136,51 +136,7 @@ impl IsoDateRecord {
         largest_unit: &JsString,
     ) -> JsResult<temporal::duration::DurationRecord> {
         debug_assert!(self.is_valid());
-        // 1. Assert: IsValidISODate(y1, m1, d1) is true.
-        // 2. Assert: IsValidISODate(y2, m2, d2) is true.
-        // 3. If largestUnit is "year" or "month", then
-        // a. Let sign be -(! CompareISODate(y1, m1, d1, y2, m2, d2)).
-        // b. If sign is 0, return ! CreateDateDurationRecord(0, 0, 0, 0).
-        // c. Let start be the Record { [[Year]]: y1, [[Month]]: m1, [[Day]]: d1 }.
-        // d. Let end be the Record { [[Year]]: y2, [[Month]]: m2, [[Day]]: d2 }.
-        // e. Let years be end.[[Year]] - start.[[Year]].
-        // f. Let mid be ! AddISODate(y1, m1, d1, years, 0, 0, 0, "constrain").
-        // g. Let midSign be -(! CompareISODate(mid.[[Year]], mid.[[Month]], mid.[[Day]], y2, m2, d2)).
-        // h. If midSign is 0, then
-        // i. If largestUnit is "year", return ! CreateDateDurationRecord(years, 0, 0, 0).
-        // ii. Return ! CreateDateDurationRecord(0, years × 12, 0, 0).
-        // i. Let months be end.[[Month]] - start.[[Month]].
-        // j. If midSign is not equal to sign, then
-        // i. Set years to years - sign.
-        // ii. Set months to months + sign × 12.
-        // k. Set mid to ! AddISODate(y1, m1, d1, years, months, 0, 0, "constrain").
-        // l. Set midSign to -(! CompareISODate(mid.[[Year]], mid.[[Month]], mid.[[Day]], y2, m2, d2)).
-        // m. If midSign is 0, then
-        // i. If largestUnit is "year", return ! CreateDateDurationRecord(years, months, 0, 0).
-        // ii. Return ! CreateDateDurationRecord(0, months + years × 12, 0, 0).
-        // n. If midSign is not equal to sign, then
-        // i. Set months to months - sign.
-        // ii. Set mid to ! AddISODate(y1, m1, d1, years, months, 0, 0, "constrain").
-        // o. If mid.[[Month]] = end.[[Month]], then
-        // i. Assert: mid.[[Year]] = end.[[Year]].
-        // ii. Let days be end.[[Day]] - mid.[[Day]].
-        // p. Else,
-        // i. If sign < 0, let days be -mid.[[Day]] - (ISODaysInMonth(end.[[Year]], end.[[Month]]) - end.[[Day]]).
-        // q. Else, let days be end.[[Day]] + (ISODaysInMonth(mid.[[Year]], mid.[[Month]]) - mid.[[Day]]).
-        // r. If largestUnit is "month", then
-        // i. Set months to months + years × 12.
-        // ii. Set years to 0.
-        // s. Return ! CreateDateDurationRecord(years, months, 0, days).
-        // 4. Else,
-        // a. Assert: largestUnit is "day" or "week".
-        // b. Let epochDays1 be ISODateToEpochDays(y1, m1 - 1, d1).
-        // c. Let epochDays2 be ISODateToEpochDays(y2, m2 - 1, d2).
-        // d. Let days be epochDays2 - epochDays1.
-        // e. Let weeks be 0.
-        // f. If largestUnit is "week", then
-        // i. Set weeks to truncate(days / 7).
-        // ii. Set days to remainder(days, 7).
-        // g. Return ! CreateDateDurationRecord(0, 0, weeks, days).
+        // TODO: Implement on `ICU4X`.
 
         Err(JsNativeError::range()
             .with_message("not yet implemented.")

boa_parser/src/temporal/date_time.rs

@@ -17,13 +17,14 @@ use boa_ast::{
 
 use super::grammar::{is_annotation_open, is_hyphen};
 
-/// `AnnotatedDateTime`
+/// This function handles parsing for [`AnnotatedDateTime`][datetime],
+/// [`AnnotatedDateTimeTimeRequred`][time], and
+/// [`TemporalInstantString.`][instant] according to the requirements
+/// provided via Spec.
 ///
-/// Defined in Temporal Proposal as follows:
-///
-/// `AnnotatedDateTime`[Zoned] :
-///     [~Zoned] `DateTime` `TimeZoneAnnotation`(opt) `Annotations`(opt)
-///     [+Zoned] `DateTime` `TimeZoneAnnotation` `Annotations`(opt)
+/// [datetime]: https://tc39.es/proposal-temporal/#prod-AnnotatedDateTime
+/// [time]: https://tc39.es/proposal-temporal/#prod-AnnotatedDateTimeTimeRequired
+/// [instant]: https://tc39.es/proposal-temporal/#prod-TemporalInstantString
 pub(crate) fn parse_annotated_date_time(
     zoned: bool,
     time_required: bool,

boa_parser/src/temporal/mod.rs

@@ -19,44 +19,51 @@ use boa_ast::temporal::{DateRecord, DurationParseRecord, IsoParseRecord, TzIdent
 // is ~100 characters (+10-20 for some calendars):
 // +001970-01-01T00:00:00.000000000+00:00:00.000000000[!America/Argentina/ComodRivadavia][!u-ca=iso8601]
 
-/// Parse a `TemporalDateTimeString`.
+/// Parse a [`TemporalDateTimeString`][proposal].
+///
+/// [proposal]: https://tc39.es/proposal-temporal/#prod-TemporalDateTimeString
 #[derive(Debug, Clone, Copy)]
 pub struct TemporalDateTimeString;
 
 impl TemporalDateTimeString {
-    /// Parses a targeted `DateTimeString`
+    /// Parses a targeted string as a `DateTime`.
     ///
     /// # Errors
     ///
     /// The parse will error if the provided target is not valid
-    /// ISO8601 grammar..
+    /// ISO8601 grammar.
     pub fn parse(zoned: bool, cursor: &mut IsoCursor) -> ParseResult<IsoParseRecord> {
         date_time::parse_annotated_date_time(zoned, false, false, cursor)
     }
 }
 
-/// Parse a `TemporalTimeZoneString`
+/// Parse a [`TemporalTimeZoneString`][proposal].
+///
+/// [proposal]: https://tc39.es/proposal-temporal/#prod-TemporalTimeZoneString
 #[derive(Debug, Clone, Copy)]
 pub struct TemporalTimeZoneString;
 
+// TODO: Return a IsoParseRecord instead of a `TzIdentifier`.
 impl TemporalTimeZoneString {
-    /// Parses a targeted `TimeZoneString`
+    /// Parses a targeted string as a `TimeZone`.
     ///
     /// # Errors
     ///
     /// The parse will error if the provided target is not valid
-    /// ISO8601 grammar..
+    /// ISO8601 grammar.
     pub fn parse(cursor: &mut IsoCursor) -> ParseResult<TzIdentifier> {
         time_zone::parse_tz_identifier(cursor)
     }
 }
 
-/// Parse a `TemporalYearMonthString`
+/// Parse a [`TemporalYearMonthString`][proposal]
+///
+/// [proposal]: https://tc39.es/proposal-temporal/#prod-TemporalYearMonthString
 #[derive(Debug, Clone, Copy)]
 pub struct TemporalYearMonthString;
 
 impl TemporalYearMonthString {
-    /// Parses a targeted `YearMonthString`.
+    /// Parses a targeted string as a `YearMonth`
     ///
     /// # Errors
     ///
@@ -90,12 +97,14 @@ impl TemporalYearMonthString {
     }
 }
 
-/// Parse a `TemporalMonthDayString`
+/// Parse a [`TemporalMonthDayString`][proposal]
+///
+/// [proposal]: https://tc39.es/proposal-temporal/#prod-TemporalMonthDayString
 #[derive(Debug, Clone, Copy)]
 pub struct TemporalMonthDayString;
 
 impl TemporalMonthDayString {
-    /// Parses a targeted `MonthDayString`.
+    /// Parses a targeted string as a `MonthDay`.
     ///
     /// # Errors
     ///
@@ -129,12 +138,14 @@ impl TemporalMonthDayString {
     }
 }
 
-/// Parser for a `Temporal.Instant` string.
+/// Parser for a [`TemporalInstantString`][proposal].
+///
+/// [proposal]: https://tc39.es/proposal-temporal/#prod-TemporalInstantString
 #[derive(Debug, Clone, Copy)]
 pub struct TemporalInstantString;
 
 impl TemporalInstantString {
-    /// Parses a targeted `Instant` String.
+    /// Parses a targeted string as an `Instant`.
     ///
     /// # Errors
     ///
@@ -145,12 +156,16 @@ impl TemporalInstantString {
     }
 }
 
-/// Parser for a `Temporal.Instant` string.
+// TODO: implement TemporalTimeString.
+
+/// Parser for a [`TemporalDurationString`][proposal].
+///
+/// [proposal]: https://tc39.es/proposal-temporal/#prod-TemporalDurationString
 #[derive(Debug, Clone, Copy)]
 pub struct TemporalDurationString;
 
 impl TemporalDurationString {
-    /// Parses a targeted `Instant` String.
+    /// Parses a targeted string as a `Duration`.
     ///
     /// # Errors
     ///