Expand API documentation for DateTime and Timestamp classes

- Enhanced documentation for `DateTimeRFC3339`, `DateTimeW3C`, `DateTimeRFC3339Extended`, and `DateTimeAtom` to clarify formatting behavior, parsing, timezone handling, and utilization of strict `DateTimeType` mechanics.
- Updated examples to demonstrate factory methods (`fromString` and `fromDateTime`), round-trip guarantees, and output format normalization.
- Improved documentation for `TimestampMilliseconds` and `TimestampSeconds` to detail strict parsing via `DateTimeType`, consistent error aggregation, and output guarantees.
- Standardized

Author: georgedeploy

src/DateTime/DateTimeAtom.php

@@ -14,9 +14,17 @@
 use PhpTypedValues\Undefined\Alias\Undefined;
 
 /**
- * ATOM RFC 3339 format based on ISO 8601.
+ * Date-time value formatted using PHP's DATE_ATOM (RFC 3339 based on ISO 8601).
  *
- * Example "2025-01-02T03:04:05+00:00"
+ * Provides strict parsing with detailed error aggregation via the base
+ * DateTimeType, preserves the exact offset, and guarantees round-trip
+ * formatting using DATE_ATOM.
+ *
+ * Example
+ *  - $v = DateTimeAtom::fromString('2025-01-02T03:04:05+00:00');
+ *    $v->toString(); // "2025-01-02T03:04:05+00:00"
+ *  - $v = DateTimeAtom::fromDateTime(new DateTimeImmutable('2030-12-31T23:59:59+03:00'));
+ *    (string) $v; // "2030-12-31T23:59:59+03:00"
  *
  * @psalm-immutable
  */

src/DateTime/DateTimeRFC3339.php

@@ -14,9 +14,17 @@
 use PhpTypedValues\Undefined\Alias\Undefined;
 
 /**
- * RFC 3339 format based on ISO 8601.
+ * Date-time value formatted using PHP's DATE_RFC3339 (RFC 3339 based on ISO 8601).
  *
- * Example "2025-01-02T03:04:05+00:00"
+ * Leverages the common DateTimeType parsing that aggregates parser errors and
+ * warnings, enforces strict round-trip formatting, and normalizes timezone
+ * handling. Guarantee output formatted with DATE_RFC3339.
+ *
+ * Example
+ *  - $v = DateTimeRFC3339::fromString('2025-01-02T03:04:05+00:00');
+ *    $v->toString(); // "2025-01-02T03:04:05+00:00"
+ *  - $v = DateTimeRFC3339::fromDateTime(new DateTimeImmutable('2030-12-31T23:59:59+03:00'));
+ *    (string) $v; // "2030-12-31T23:59:59+03:00"
  *
  * @psalm-immutable
  */

src/DateTime/DateTimeRFC3339Extended.php

@@ -14,9 +14,18 @@
 use PhpTypedValues\Undefined\Alias\Undefined;
 
 /**
- * RFC 3339 EXTENDED format based on ISO 8601 (with microseconds).
+ * Date-time value formatted using PHP's DATE_RFC3339_EXTENDED (RFC 3339 with microseconds).
  *
- * Example "2025-01-02T03:04:05.123456+00:00"
+ * Inherits strict parsing and validation from DateTimeType, including detailed
+ * parser error aggregation and exact round-trip checks. Ensures output
+ * formatting with DATE_RFC3339_EXTENDED, preserving fractional seconds and
+ * timezone offset.
+ *
+ * Example
+ *  - $v = DateTimeRFC3339Extended::fromString('2025-01-02T03:04:05.123456+00:00');
+ *    $v->toString(); // "2025-01-02T03:04:05.123456+00:00"
+ *  - $v = DateTimeRFC3339Extended::fromDateTime(new DateTimeImmutable('2030-12-31T23:59:59.654321+03:00'));
+ *    (string) $v; // "2030-12-31T23:59:59.654321+03:00"
  *
  * @psalm-immutable
  */

src/DateTime/DateTimeW3C.php

@@ -14,9 +14,17 @@
 use PhpTypedValues\Undefined\Alias\Undefined;
 
 /**
- * W3C RFC 3339 format based on ISO 8601.
+ * Date-time value formatted using PHP's DATE_W3C (W3C profile of ISO 8601/RFC 3339).
  *
- * Example "2025-01-02T03:04:05+00:00"
+ * Uses the shared DateTimeType mechanics for strict parsing with aggregated
+ * errors and warnings, exact round-trip verification, and normalized timezone
+ * handling. Guarantees output using DATE_W3C format.
+ *
+ * Example
+ *  - $v = DateTimeW3C::fromString('2025-01-02T03:04:05+00:00');
+ *    $v->toString(); // "2025-01-02T03:04:05+00:00"
+ *  - $v = DateTimeW3C::fromDateTime(new DateTimeImmutable('2030-12-31T23:59:59+03:00'));
+ *    (string) $v; // "2030-12-31T23:59:59+03:00"
  *
  * @psalm-immutable
  */

src/DateTime/Timestamp/TimestampMilliseconds.php

@@ -14,9 +14,18 @@
 use function sprintf;
 
 /**
- * Unix timestamp in milliseconds since Unix epoch (UTC).
+ * Unix timestamp value in milliseconds since the Unix epoch (UTC).
  *
- * Example "1732445696123"
+ * Accepts a strictly numeric milliseconds string and converts it to an
+ * internal DateTimeImmutable with microsecond precision. Parsing and
+ * validation leverage DateTimeType, including detailed error aggregation and
+ * strict round‑trip verification. Output is rendered back to milliseconds.
+ *
+ * Example
+ *  - $v = TimestampMilliseconds::fromString('1732445696123');
+ *    $v->toString(); // "1732445696123"
+ *  - $v = TimestampMilliseconds::fromString('0');
+ *    (string) $v; // "0"
  *
  * @psalm-immutable
  */

src/DateTime/Timestamp/TimestampSeconds.php

@@ -11,9 +11,16 @@
 use PhpTypedValues\Undefined\Alias\Undefined;
 
 /**
- * Unix timestamp (seconds since Unix epoch, UTC).
+ * Unix timestamp value in whole seconds since the Unix epoch (UTC).
  *
- * Example "1732445696"
+ * Parses and formats using the 'U' pattern via the base DateTimeType, which
+ * performs strict error aggregation, round‑trip validation, and timezone
+ * normalization. Output has been guaranteed to be seconds since epoch as a string.
+ *
+ * Example
+ *  - $v = TimestampSeconds::fromString('1732445696');
+ *    $v->toString(); // "1732445696"
+ *  - (string) TimestampSeconds::fromString('0'); // "0"
  *
  * @psalm-immutable
  */