Add documentation and doctests for builtins (#360)

Added documentation and doctests for builtin types, including MDN
references and examples on how to use them with popular use cases.

#107

Author: blarfoon

src/builtins/core/date.rs

@@ -154,6 +154,74 @@ impl PartialDate {
 }
 
 /// The native Rust implementation of `Temporal.PlainDate`.
+///
+/// Represents a calendar date without any time or timezone
+/// information. Useful for dates where the specific time of day doesn't matter,
+/// such as deadlines, birth dates, or historical events.
+///
+/// Uses the ISO 8601 calendar (proleptic Gregorian calendar) by default, with
+/// support for other calendar systems when needed.
+///
+/// ## Examples
+///
+/// ### Creating dates
+///
+/// ```rust
+/// use temporal_rs::{PlainDate, Calendar};
+///
+/// // Create a date using the ISO calendar
+/// let christmas = PlainDate::try_new_iso(2024, 12, 25).unwrap();
+/// assert_eq!(christmas.year(), 2024);
+/// assert_eq!(christmas.month(), 12);
+/// assert_eq!(christmas.day(), 25);
+///
+/// // Explicit calendar specification
+/// let date = PlainDate::try_new(2024, 12, 25, Calendar::default()).unwrap();
+/// assert_eq!(date.year(), 2024);
+/// assert_eq!(christmas, date); // Both represent the same date
+/// ```
+///
+/// ### Date arithmetic operations
+///
+/// ```rust
+/// use temporal_rs::{PlainDate, Duration};
+/// use core::str::FromStr;
+///
+/// let start = PlainDate::try_new_iso(2024, 1, 15).unwrap();
+///
+/// // Add one month
+/// let later = start.add(&Duration::from_str("P1M").unwrap(), None).unwrap();
+/// assert_eq!(later.month(), 2); // Results in 2024-02-15
+/// assert_eq!(later.day(), 15);
+///
+/// // Calculate duration between dates
+/// let new_year = PlainDate::try_new_iso(2024, 1, 1).unwrap();
+/// let diff = new_year.until(&start, Default::default()).unwrap();
+/// assert_eq!(diff.days(), 14);
+/// ```
+///
+/// ### Parsing ISO 8601 date strings
+///
+/// ```rust
+/// use temporal_rs::PlainDate;
+/// use core::str::FromStr;
+///
+/// // Standard ISO date format
+/// let date = PlainDate::from_str("2024-03-15").unwrap();
+/// assert_eq!(date.year(), 2024);
+/// assert_eq!(date.month(), 3);
+/// assert_eq!(date.day(), 15);
+///
+/// // With explicit calendar annotation
+/// let date2 = PlainDate::from_str("2024-03-15[u-ca=iso8601]").unwrap();
+/// assert_eq!(date, date2);
+/// ```
+///
+/// ## Reference
+///
+/// For more information, see the [MDN documentation][mdn-plaindate].
+///
+/// [mdn-plaindate]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/PlainDate
 #[non_exhaustive]
 #[derive(Debug, Default, Clone, PartialEq, Eq)]
 pub struct PlainDate {

src/builtins/core/datetime.rs

@@ -54,12 +54,109 @@ impl PartialDateTime {
     }
 }
 
-// TODO: Example doctest
 /// The native Rust implementation of a Temporal `PlainDateTime`.
 ///
-/// The `PlainDateTime` represents a date and time without a
-/// time zone. The fundemental represenation of a `PlainDateTime`
-/// is it's internal ISO date and time fields and a calendar.
+/// Combines a date and time into a single value representing a specific moment
+/// in calendar time, such as "2024-03-15T14:30:45". Unlike `Instant`,
+/// a `PlainDateTime` does not include timezone information.
+///
+/// Use `PlainDateTime` when you need to represent a specific date and time but
+/// timezone handling is not required, or when working with local times that
+/// don't need to be converted across timezones.
+///
+/// ## Examples
+///
+/// ### Creating date and time values
+///
+/// ```rust
+/// use temporal_rs::PlainDateTime;
+/// use core::str::FromStr;
+///
+/// // Create a specific date and time from IXDTF string
+/// let meeting = PlainDateTime::from_str("2024-03-15T14:30:45.123456789").unwrap();
+/// assert_eq!(meeting.year(), 2024);
+/// assert_eq!(meeting.hour(), 14);
+/// assert_eq!(meeting.minute(), 30);
+/// ```
+///
+/// ### Parsing ISO 8601 datetime strings
+///
+/// ```rust
+/// use temporal_rs::PlainDateTime;
+/// use core::str::FromStr;
+///
+/// let dt = PlainDateTime::from_str("2024-03-15T14:30:45.123456789").unwrap();
+/// assert_eq!(dt.year(), 2024);
+/// assert_eq!(dt.month(), 3);
+/// assert_eq!(dt.day(), 15);
+/// assert_eq!(dt.hour(), 14);
+/// assert_eq!(dt.minute(), 30);
+/// assert_eq!(dt.second(), 45);
+/// assert_eq!(dt.millisecond(), 123);
+/// assert_eq!(dt.microsecond(), 456);
+/// assert_eq!(dt.nanosecond(), 789);
+/// ```
+///
+/// ### DateTime arithmetic
+///
+/// ```rust
+/// use temporal_rs::{PlainDateTime, Duration};
+/// use core::str::FromStr;
+///
+/// let dt = PlainDateTime::from_str("2024-01-15T12:00:00").unwrap();
+///
+/// // Add duration
+/// let later = dt.add(&Duration::from_str("P1M2DT3H4M").unwrap(), None).unwrap();
+/// assert_eq!(later.month(), 2);
+/// assert_eq!(later.day(), 17);
+/// assert_eq!(later.hour(), 15);
+/// assert_eq!(later.minute(), 4);
+///
+/// // Calculate difference
+/// let earlier = PlainDateTime::from_str("2024-01-10T10:30:00").unwrap();
+/// let duration = earlier.until(&dt, Default::default()).unwrap();
+/// assert_eq!(duration.days(), 5);
+/// assert_eq!(duration.hours(), 1);
+/// assert_eq!(duration.minutes(), 30);
+/// ```
+///
+/// ### Working with partial fields
+///
+/// ```rust
+/// use temporal_rs::{PlainDateTime, partial::{PartialDateTime, PartialDate, PartialTime}};
+/// use core::str::FromStr;
+///
+/// let dt = PlainDateTime::from_str("2024-01-15T12:30:45").unwrap();
+///
+/// // Change only the hour
+/// let partial = PartialDateTime::new()
+///     .with_partial_time(PartialTime::new().with_hour(Some(18)));
+/// let modified = dt.with(partial, None).unwrap();
+/// assert_eq!(modified.hour(), 18);
+/// assert_eq!(modified.minute(), 30); // unchanged
+/// assert_eq!(modified.second(), 45); // unchanged
+/// ```
+///
+/// ### Converting to other types
+///
+/// ```rust
+/// use temporal_rs::{PlainDateTime, PlainTime};
+/// use core::str::FromStr;
+///
+/// let dt = PlainDateTime::from_str("2024-03-15T14:30:45").unwrap();
+///
+/// // Extract date component
+/// let date = dt.to_plain_date().unwrap();
+/// assert_eq!(date.year(), 2024);
+/// assert_eq!(date.month(), 3);
+/// assert_eq!(date.day(), 15);
+///
+/// // Extract time component
+/// let time = dt.to_plain_time().unwrap();
+/// assert_eq!(time.hour(), 14);
+/// assert_eq!(time.minute(), 30);
+/// assert_eq!(time.second(), 45);
+/// ```
 ///
 /// ## Reference
 ///

src/builtins/core/duration.rs

@@ -68,8 +68,152 @@ impl PartialDuration {
 
 /// 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.
+/// Represents a span of time such as "2 hours and 30 minutes" or "3 years, 2 months".
+/// Unlike `Instant` which represents a specific moment in time, Duration represents
+/// the amount of time between two moments.
+///
+/// A Duration consists of two categories of components:
+/// - Date components: years, months, weeks, and days
+/// - Time components: hours, minutes, seconds, and subsecond units (nanosecond precision)
+///
+/// Note that date arithmetic can be complex. For example, adding "1 month" to January 31st
+/// could result in February 28th (non-leap year), February 29th (leap year), or March 3rd
+/// (if you overflow February), depending on the calendar system and overflow handling.
+///
+/// ## Examples
+///
+/// ### Creating durations
+///
+/// ```rust
+/// use temporal_rs::Duration;
+///
+/// // Create a duration with specific components
+/// let vacation_duration = Duration::new(
+///     0, 0, 2, 3,    // 2 weeks and 3 days
+///     0, 0, 0,       // no time components
+///     0, 0, 0        // no subsecond components
+/// ).unwrap();
+///
+/// assert_eq!(vacation_duration.weeks(), 2);
+/// assert_eq!(vacation_duration.days(), 3);
+/// ```
+///
+/// ### Parsing ISO 8601 duration strings
+///
+/// ```rust
+/// use temporal_rs::Duration;
+/// use core::str::FromStr;
+///
+/// // Complex duration with multiple components
+/// let complex = Duration::from_str("P1Y2M3DT4H5M6.789S").unwrap();
+/// assert_eq!(complex.years(), 1);
+/// assert_eq!(complex.months(), 2);
+/// assert_eq!(complex.days(), 3);
+/// assert_eq!(complex.hours(), 4);
+/// assert_eq!(complex.minutes(), 5);
+/// assert_eq!(complex.seconds(), 6);
+///
+/// // Time-only duration
+/// let movie_length = Duration::from_str("PT2H30M").unwrap();
+/// assert_eq!(movie_length.hours(), 2);
+/// assert_eq!(movie_length.minutes(), 30);
+///
+/// // Negative durations
+/// let negative = Duration::from_str("-P1D").unwrap();
+/// assert_eq!(negative.days(), -1);
+/// ```
+///
+/// ### Duration arithmetic
+///
+/// ```rust
+/// use temporal_rs::Duration;
+/// use core::str::FromStr;
+///
+/// let commute_time = Duration::from_str("PT45M").unwrap();
+/// let lunch_break = Duration::from_str("PT1H").unwrap();
+///
+/// // Add durations together
+/// let total_time = commute_time.add(&lunch_break).unwrap();
+/// assert_eq!(total_time.hours(), 1);    // Results in 1 hour 45 minutes
+/// assert_eq!(total_time.minutes(), 45);
+///
+/// // Subtract duration components
+/// let shortened = lunch_break.subtract(&Duration::from_str("PT15M").unwrap()).unwrap();
+/// assert_eq!(shortened.minutes(), 45);
+/// ```
+///
+/// ### Date arithmetic with durations
+///
+/// ```rust
+/// use temporal_rs::{PlainDate, Duration, options::ArithmeticOverflow};
+/// use core::str::FromStr;
+///
+/// // January 31st in different years
+/// let jan_31_2023 = PlainDate::try_new_iso(2023, 1, 31).unwrap();
+/// let jan_31_2024 = PlainDate::try_new_iso(2024, 1, 31).unwrap(); // leap year
+///
+/// let one_month = Duration::from_str("P1M").unwrap();
+///
+/// // Adding 1 month to Jan 31st gives different results:
+/// let feb_2023 = jan_31_2023.add(&one_month, Some(ArithmeticOverflow::Constrain)).unwrap();
+/// let feb_2024 = jan_31_2024.add(&one_month, Some(ArithmeticOverflow::Constrain)).unwrap();
+///
+/// // 2023: Jan 31 + 1 month = Feb 28 (no Feb 31st exists)
+/// assert_eq!(feb_2023.day(), 28);
+/// // 2024: Jan 31 + 1 month = Feb 29 (leap year)  
+/// assert_eq!(feb_2024.day(), 29);
+/// ```
+///
+/// ### Working with partial durations
+///
+/// ```rust
+/// use temporal_rs::{Duration, partial::PartialDuration};
+///
+/// let partial = PartialDuration {
+///     hours: Some(3),
+///     minutes: Some(45),
+///     ..Default::default()
+/// };
+///
+/// let duration = Duration::from_partial_duration(partial).unwrap();
+/// assert_eq!(duration.hours(), 3);
+/// assert_eq!(duration.minutes(), 45);
+/// assert_eq!(duration.days(), 0); // other fields default to 0
+/// ```
+///
+/// ### Duration properties
+///
+/// ```rust
+/// use temporal_rs::Duration;
+/// use core::str::FromStr;
+///
+/// let duration = Duration::from_str("P1Y2M3D").unwrap();
+///
+/// // Check if duration is zero
+/// assert!(!duration.is_zero());
+///
+/// // Get the sign of the duration
+/// let sign = duration.sign();
+/// // Note: This particular duration has mixed signs which affects the overall sign
+///
+/// // Get absolute value
+/// let abs_duration = duration.abs();
+/// assert_eq!(abs_duration.years(), 1);
+/// assert_eq!(abs_duration.months(), 2);
+/// assert_eq!(abs_duration.days(), 3);
+///
+/// // Negate duration
+/// let negated = duration.negated();
+/// assert_eq!(negated.years(), -1);
+/// assert_eq!(negated.months(), -2);
+/// assert_eq!(negated.days(), -3);
+/// ```
+///
+/// ## Reference
+///
+/// For more information, see the [MDN documentation][mdn-duration].
+///
+/// [mdn-duration]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Temporal/Duration
 #[non_exhaustive]
 #[derive(Debug, Clone, Copy, Default)]
 pub struct Duration {