General updates to temporal_rs's exports and docs (#575)

This PR adds some documentation to some of the modules and `sys`
exports. It also removes DateDuration from being a top level export
opting instead to export it from a new `duration` module.

It also doc hides some of the constants.

---------

Co-authored-by: Manish Goregaokar <[email protected]>

Author: nekevss

src/builtins/compiled/duration/tests.rs

@@ -1,9 +1,10 @@
 use crate::{
+    duration::DateDuration,
     options::{
         OffsetDisambiguation, RelativeTo, RoundingIncrement, RoundingMode, RoundingOptions, Unit,
     },
     partial::PartialDuration,
-    Calendar, DateDuration, PlainDate, TimeZone, ZonedDateTime,
+    Calendar, PlainDate, TimeZone, ZonedDateTime,
 };
 
 use core::{num::NonZeroU32, str::FromStr};

src/builtins/core/plain_time.rs

@@ -1,14 +1,17 @@
 //! This module implements `Time` and any directly related algorithms.
 
 use crate::{
-    builtins::{core::Duration, duration::normalized::InternalDurationRecord},
+    builtins::{
+        core::{DateDuration, Duration},
+        duration::normalized::InternalDurationRecord,
+    },
     iso::IsoTime,
     options::{
         DifferenceOperation, DifferenceSettings, Overflow, ResolvedRoundingOptions,
         RoundingOptions, ToStringRoundingOptions, Unit, UnitGroup,
     },
     parsers::{parse_time, IxdtfStringBuilder},
-    DateDuration, TemporalError, TemporalResult,
+    TemporalError, TemporalResult,
 };
 use alloc::string::String;
 use core::str::FromStr;

src/lib.rs

@@ -309,7 +309,7 @@ pub use error::TemporalError;
 pub use sys::Temporal;
 
 pub mod partial {
-    //! Partial Date/Time component records.
+    //! Partial date and time component records
     //!
     //! The partial records are `temporal_rs`'s method of addressing
     //! `TemporalFields` in the specification.
@@ -322,27 +322,33 @@ pub mod partial {
 pub mod parsed_intermediates;
 
 // TODO: Potentially bikeshed how `EpochNanoseconds` should be exported.
+/// A module for structs related to the UNIX epoch
 pub mod unix_time {
     pub use timezone_provider::epoch_nanoseconds::EpochNanoseconds;
 }
 
-/// The `Now` module includes type for building a Now.
+/// The `Now` module includes type for building a Now
 pub mod now {
     pub use crate::builtins::Now;
 }
 
-/// This module exports all of the field types.
+/// Duration related types
+pub mod duration {
+    pub use crate::builtins::DateDuration;
+}
+
+/// Calendar field records
 pub mod fields {
     pub use crate::builtins::{
         calendar::{CalendarFields, YearMonthCalendarFields},
         DateTimeFields, ZonedDateTimeFields,
     };
 }
 
+// TODO: Should we be exporting MonthCode and UtcOffset here.
 pub use crate::builtins::{
     calendar::{Calendar, MonthCode},
     core::timezone::{TimeZone, UtcOffset},
-    core::DateDuration,
     Duration, Instant, PlainDate, PlainDateTime, PlainMonthDay, PlainTime, PlainYearMonth,
     ZonedDateTime,
 };
@@ -428,15 +434,19 @@ impl Sign {
 }
 
 // Relevant numeric constants
+
 /// Nanoseconds per day constant: 8.64e+13
+#[doc(hidden)]
 pub const NS_PER_DAY: u64 = MS_PER_DAY as u64 * 1_000_000;
+#[doc(hidden)]
 pub const NS_PER_DAY_NONZERO: core::num::NonZeroU128 =
     if let Some(nz) = core::num::NonZeroU128::new(NS_PER_DAY as u128) {
         nz
     } else {
         unreachable!()
     };
 /// Milliseconds per day constant: 8.64e+7
+#[doc(hidden)]
 pub const MS_PER_DAY: u32 = 24 * 60 * 60 * 1000;
 /// Max Instant nanosecond constant
 #[doc(hidden)]

src/sys.rs

@@ -21,16 +21,21 @@ use web_time::{SystemTime, UNIX_EPOCH};
 // pub struct Temporal(SystemTime<DefaultSystemClock, DefaultSystemTimeZone>)
 //
 
+/// The Temporal object for accessing current system time
 #[cfg(feature = "sys")]
 pub struct Temporal;
 
 #[cfg(feature = "sys")]
 impl Temporal {
+    /// Get a `Now` object for the default host system.
     pub fn now() -> Now<DefaultHostSystem> {
         Now::new(DefaultHostSystem)
     }
 }
 
+/// A default host system implementation
+///
+/// This implementation is backed by [`SystemTime`] and [`iana_time_zone`]
 #[cfg(feature = "sys")]
 pub struct DefaultHostSystem;
 

temporal_capi/src/duration.rs

@@ -21,7 +21,7 @@ pub mod ffi {
 
     #[diplomat::opaque]
     #[diplomat::transparent_convert]
-    pub struct DateDuration(pub(crate) temporal_rs::DateDuration);
+    pub struct DateDuration(pub(crate) temporal_rs::duration::DateDuration);
 
     pub struct PartialDuration {
         pub years: DiplomatOption<i64>,
@@ -58,7 +58,7 @@ pub mod ffi {
             weeks: i64,
             days: i64,
         ) -> Result<Box<Self>, TemporalError> {
-            temporal_rs::DateDuration::new(years, months, weeks, days)
+            temporal_rs::duration::DateDuration::new(years, months, weeks, days)
                 .map(|x| Box::new(DateDuration(x)))
                 .map_err(Into::into)
         }