boa_temporal structure changes and docs update (#3504)

* API changes and docs update

* cargo fmt all

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

@@ -24,7 +24,7 @@ use crate::{
 use boa_gc::{Finalize, Trace};
 use boa_profiler::Profiler;
 use boa_temporal::{
-    calendar::{
+    components::calendar::{
         AvailableCalendars, CalendarDateLike, CalendarFieldsType, CalendarSlot,
         CALENDAR_PROTOCOL_METHODS,
     },

boa_engine/src/builtins/temporal/calendar/object.rs

@@ -9,15 +9,12 @@ use std::any::Any;
 
 use boa_macros::utf16;
 use boa_temporal::{
-    calendar::{CalendarDateLike, CalendarProtocol},
-    date::Date,
-    duration::Duration,
-    error::TemporalError,
-    fields::TemporalFields,
-    month_day::MonthDay,
+    components::{
+        calendar::{CalendarDateLike, CalendarFieldsType, CalendarProtocol},
+        Date, Duration, MonthDay, YearMonth,
+    },
     options::ArithmeticOverflow,
-    year_month::YearMonth,
-    TemporalResult, TinyAsciiStr,
+    TemporalError, TemporalFields, TemporalResult, TinyAsciiStr,
 };
 use num_traits::ToPrimitive;
 use plain_date::PlainDate;
@@ -821,22 +818,15 @@ impl CalendarProtocol for CustomRuntimeCalendar {
 
     // TODO: Determine fate of fn fields()
 
-    fn field_descriptors(
-        &self,
-        _: boa_temporal::calendar::CalendarFieldsType,
-    ) -> Vec<(String, bool)> {
+    fn field_descriptors(&self, _: CalendarFieldsType) -> Vec<(String, bool)> {
         Vec::default()
     }
 
     fn field_keys_to_ignore(&self, _: Vec<String>) -> Vec<String> {
         Vec::default()
     }
 
-    fn resolve_fields(
-        &self,
-        _: &mut TemporalFields,
-        _: boa_temporal::calendar::CalendarFieldsType,
-    ) -> TemporalResult<()> {
+    fn resolve_fields(&self, _: &mut TemporalFields, _: CalendarFieldsType) -> TemporalResult<()> {
         Ok(())
     }
 

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

@@ -16,7 +16,7 @@ use crate::{
 };
 use boa_gc::{Finalize, Trace};
 use boa_profiler::Profiler;
-use boa_temporal::{duration::Duration as InnerDuration, options::TemporalUnit};
+use boa_temporal::{components::Duration as InnerDuration, options::TemporalUnit};
 
 use super::{
     options::{get_temporal_rounding_increment, get_temporal_unit, TemporalUnitGroup},

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

@@ -20,7 +20,7 @@ use crate::{
 };
 use boa_gc::{Finalize, Trace};
 use boa_profiler::Profiler;
-use boa_temporal::{duration::Duration, options::TemporalUnit};
+use boa_temporal::{components::Duration, options::TemporalUnit};
 
 use super::{ns_max_instant, ns_min_instant, MIS_PER_DAY, MS_PER_DAY, NS_PER_DAY};
 

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

@@ -16,7 +16,10 @@ use crate::{
 };
 use boa_gc::{Finalize, Trace};
 use boa_profiler::Profiler;
-use boa_temporal::{date::Date as InnerDate, datetime::DateTime, options::ArithmeticOverflow};
+use boa_temporal::{
+    components::{Date as InnerDate, DateTime},
+    options::ArithmeticOverflow,
+};
 
 use super::{calendar, PlainDateTime, ZonedDateTime};
 

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

@@ -12,7 +12,7 @@ use crate::{
 use boa_gc::{Finalize, Trace};
 use boa_profiler::Profiler;
 
-use boa_temporal::datetime::DateTime as InnerDateTime;
+use boa_temporal::components::DateTime as InnerDateTime;
 
 /// The `Temporal.PlainDateTime` object.
 #[derive(Debug, Clone, Trace, Finalize, JsData)]

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

@@ -12,7 +12,7 @@ use crate::{
 use boa_gc::{Finalize, Trace};
 use boa_profiler::Profiler;
 
-use boa_temporal::{datetime::DateTime, month_day::MonthDay as InnerMonthDay};
+use boa_temporal::components::{DateTime, MonthDay as InnerMonthDay};
 
 /// The `Temporal.PlainMonthDay` object.
 #[derive(Debug, Clone, Trace, Finalize, JsData)]

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

@@ -14,7 +14,7 @@ use boa_gc::{Finalize, Trace};
 use boa_profiler::Profiler;
 
 use super::calendar::to_temporal_calendar_slot_value;
-use boa_temporal::{options::ArithmeticOverflow, year_month::YearMonth as InnerYearMonth};
+use boa_temporal::{components::YearMonth as InnerYearMonth, options::ArithmeticOverflow};
 
 /// The `Temporal.PlainYearMonth` object.
 #[derive(Debug, Clone, Trace, Finalize, JsData)]

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

@@ -15,7 +15,7 @@ use crate::{
 };
 use boa_gc::{Finalize, Trace};
 use boa_profiler::Profiler;
-use boa_temporal::tz::{TimeZoneSlot, TzProtocol};
+use boa_temporal::components::tz::{TimeZoneSlot, TzProtocol};
 
 /// The `Temporal.TimeZone` object.
 #[derive(Debug, Clone, Trace, Finalize, JsData)]

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

@@ -9,9 +9,7 @@ use crate::{
 };
 use boa_gc::{Finalize, Trace};
 use boa_profiler::Profiler;
-use boa_temporal::{
-    duration::Duration as TemporalDuration, zoneddatetime::ZonedDateTime as InnerZdt,
-};
+use boa_temporal::components::{Duration as TemporalDuration, ZonedDateTime as InnerZdt};
 
 /// The `Temporal.ZonedDateTime` object.
 #[derive(Debug, Clone, Finalize, Trace, JsData)]

boa_temporal/src/calendar.rs → boa_temporal/src/components/calendar.rs

@@ -1,4 +1,4 @@
-//! Temporal calendar traits and implementations.
+//! This module implements the calendar traits and related components.
 //!
 //! The goal of the calendar module of `boa_temporal` is to provide
 //! Temporal compatible calendar implementations.
@@ -11,15 +11,10 @@
 use std::{any::Any, str::FromStr};
 
 use crate::{
-    date::Date,
-    datetime::DateTime,
-    duration::Duration,
-    fields::TemporalFields,
+    components::{Date, DateTime, Duration, MonthDay, YearMonth},
     iso::{IsoDate, IsoDateSlots},
-    month_day::MonthDay,
     options::{ArithmeticOverflow, TemporalUnit},
-    year_month::YearMonth,
-    TemporalError, TemporalResult,
+    TemporalError, TemporalFields, TemporalResult,
 };
 
 use tinystr::TinyAsciiStr;

boa_temporal/src/calendar/iso.rs → boa_temporal/src/components/calendar/iso.rs

@@ -1,15 +1,11 @@
 //! Implementation of the "iso8601" calendar.
 
 use crate::{
-    date::Date,
-    duration::Duration,
+    components::{Date, Duration, MonthDay, YearMonth},
     error::TemporalError,
     fields::TemporalFields,
-    month_day::MonthDay,
     options::{ArithmeticOverflow, TemporalUnit},
-    utils,
-    year_month::YearMonth,
-    TemporalResult,
+    utils, TemporalResult,
 };
 use std::any::Any;
 

boa_temporal/src/date.rs → boa_temporal/src/components/date.rs

@@ -1,17 +1,19 @@
-//! The `PlainDate` representation.
+//! This module implements `Date` and any directly related algorithms.
 
 use crate::{
-    calendar::{AvailableCalendars, CalendarSlot},
-    datetime::DateTime,
-    duration::{DateDuration, Duration},
+    components::{
+        calendar::{AvailableCalendars, CalendarSlot},
+        duration::DateDuration,
+        DateTime, Duration,
+    },
     iso::{IsoDate, IsoDateSlots},
     options::{ArithmeticOverflow, TemporalUnit},
     parser::parse_date_time,
     TemporalError, TemporalResult,
 };
 use std::{any::Any, str::FromStr};
 
-/// The `Temporal.PlainDate` equivalent
+/// The native Rust implementation of `Temporal.PlainDate`.
 #[derive(Debug, Default, Clone)]
 pub struct Date {
     iso: IsoDate,

boa_temporal/src/datetime.rs → boa_temporal/src/components/datetime.rs

@@ -1,17 +1,16 @@
-//! Temporal implementation of `DateTime`
+//! This module implements `DateTime` any directly related algorithms.
 
 use std::str::FromStr;
 
 use crate::{
-    calendar::CalendarSlot,
-    instant::Instant,
+    components::{calendar::CalendarSlot, Instant},
     iso::{IsoDate, IsoDateSlots, IsoDateTime, IsoTime},
     options::ArithmeticOverflow,
     parser::parse_date_time,
     TemporalError, TemporalResult,
 };
 
-/// The `DateTime` struct.
+/// The native Rust implementation of `Temporal.PlainDateTime`
 #[derive(Debug, Default, Clone)]
 pub struct DateTime {
     iso: IsoDateTime,

boa_temporal/src/duration.rs → boa_temporal/src/components/duration.rs

@@ -1,15 +1,10 @@
-//! The Temporal Duration.
-//!
-//! TODO: Docs
+//! This module implements `Duration` along with it's methods and components.
 
 use crate::{
-    date::Date,
-    datetime::DateTime,
+    components::{Date, DateTime, ZonedDateTime},
     options::{ArithmeticOverflow, TemporalRoundingMode, TemporalUnit},
     parser::{duration::parse_duration, Cursor},
-    utils,
-    zoneddatetime::ZonedDateTime,
-    TemporalError, TemporalResult, NS_PER_DAY,
+    utils, TemporalError, TemporalResult, NS_PER_DAY,
 };
 use std::{any::Any, str::FromStr};
 
@@ -252,8 +247,10 @@ impl Iterator for TimeIter<'_> {
 
 // ==== `Duration` ====
 
-/// The `Duration` is a native Rust implementation of the `Duration` builtin
-/// object internal fields and is primarily defined by Abtract Operation 7.5.1-5.
+/// The native Rust implementation of `Temporal.Duration`.
+///
+/// `Duration` is made up of a `DateDuration` and `TimeDuration` as primarily
+/// defined by Abtract Operation 7.5.1-5.
 #[derive(Debug, Clone, Copy, Default)]
 pub struct Duration {
     date: DateDuration,

boa_temporal/src/instant.rs → boa_temporal/src/components/instant.rs

@@ -5,7 +5,7 @@ use crate::{TemporalError, TemporalResult};
 use num_bigint::BigInt;
 use num_traits::ToPrimitive;
 
-/// A Temporal Instant
+/// The native Rust implementation of `Temporal.Instant`
 #[derive(Debug, Clone)]
 pub struct Instant {
     pub(crate) nanos: BigInt,
@@ -69,7 +69,7 @@ pub(crate) fn is_valid_epoch_nanos(nanos: &BigInt) -> bool {
 
 #[cfg(test)]
 mod tests {
-    use crate::{instant::Instant, NS_MAX_INSTANT, NS_MIN_INSTANT};
+    use crate::{components::Instant, NS_MAX_INSTANT, NS_MIN_INSTANT};
     use num_bigint::BigInt;
     use num_traits::ToPrimitive;
 

boa_temporal/src/components/mod.rs

@@ -0,0 +1,46 @@
+//! The primary date-time components provided by Temporal.
+//!
+//! The below components are the main primitives of the `Temporal` specification:
+//!   - `Date` -> `PlainDate`
+//!   - `DateTime` -> `PlainDateTime`
+//!   - `Time` -> `PlainTime`
+//!   - `Duration` -> `Duration`
+//!   - `Instant` -> `Instant`
+//!   - `MonthDay` -> `PlainMonthDay`
+//!   - `YearMonth` -> `PlainYearMonth`
+//!   - `ZonedDateTime` -> `ZonedDateTime`
+//!
+//! The Temporal specification, along with this implementation aims to provide
+//! full support for time zones and non-gregorian calendars that are compliant
+//! with standards like ISO 8601, RFC 3339, and RFC 5545.
+
+// TODO: Expand upon above introduction.
+
+pub mod calendar;
+pub mod tz;
+
+mod date;
+mod datetime;
+pub(crate) mod duration;
+mod instant;
+mod month_day;
+mod time;
+mod year_month;
+mod zoneddatetime;
+
+#[doc(inline)]
+pub use date::Date;
+#[doc(inline)]
+pub use datetime::DateTime;
+#[doc(inline)]
+pub use duration::Duration;
+#[doc(inline)]
+pub use instant::Instant;
+#[doc(inline)]
+pub use month_day::MonthDay;
+#[doc(inline)]
+pub use time::Time;
+#[doc(inline)]
+pub use year_month::YearMonth;
+#[doc(inline)]
+pub use zoneddatetime::ZonedDateTime;

boa_temporal/src/month_day.rs → boa_temporal/src/components/month_day.rs

@@ -1,13 +1,13 @@
-//! `MonthDay`
+//! This module implements `MonthDay` and any directly related algorithms.
 
 use crate::{
-    calendar::CalendarSlot,
+    components::calendar::CalendarSlot,
     iso::{IsoDate, IsoDateSlots},
     options::ArithmeticOverflow,
     TemporalResult,
 };
 
-/// The `MonthDay` struct
+/// The native Rust implementation of `Temporal.PlainMonthDay`
 #[derive(Debug, Default, Clone)]
 pub struct MonthDay {
     iso: IsoDate,

boa_temporal/src/time.rs → boa_temporal/src/components/time.rs

@@ -1,8 +1,8 @@
-//! Temporal Time Representation.
+//! This module implements `Time` and any directly related algorithms.
 
 use crate::{iso::IsoTime, options::ArithmeticOverflow, TemporalResult};
 
-/// The Temporal `PlainTime` object.
+/// The native Rust implementation of `Temporal.PlainTime`.
 #[derive(Debug, Default, Clone, Copy)]
 #[allow(dead_code)]
 pub struct Time {

boa_temporal/src/tz.rs → boa_temporal/src/components/tz.rs

@@ -6,7 +6,8 @@ use num_bigint::BigInt;
 use num_traits::ToPrimitive;
 
 use crate::{
-    calendar::CalendarSlot, datetime::DateTime, instant::Instant, TemporalError, TemporalResult,
+    components::{calendar::CalendarSlot, DateTime, Instant},
+    TemporalError, TemporalResult,
 };
 
 /// Any object that implements the `TzProtocol` must implement the below methods/properties.

boa_temporal/src/year_month.rs → boa_temporal/src/components/year_month.rs

@@ -1,13 +1,13 @@
-//! `YearMonth`
+//! This module implements `YearMonth` and any directly related algorithms.
 
 use crate::{
-    calendar::CalendarSlot,
+    components::calendar::CalendarSlot,
     iso::{IsoDate, IsoDateSlots},
     options::ArithmeticOverflow,
     TemporalResult,
 };
 
-/// The `YearMonth` struct
+/// The native Rust implementation of `Temporal.YearMonth`.
 #[derive(Debug, Default, Clone)]
 pub struct YearMonth {
     iso: IsoDate,