Address the reviews

Author: dkhalanskyjb

core/common/src/Clock.kt

@@ -22,9 +22,9 @@ public interface Clock {
      * Returns the [Instant] corresponding to the current time, according to this clock.
      *
      * It is not guaranteed that calling [now] later will return a larger [Instant].
-     * In particular, for [System] it is completely expected that the opposite will happen,
+     * In particular, for [Clock.System] it is completely expected that the opposite will happen,
      * and it must be taken into account.
-     * See the documentation of [System] for details.
+     * See the documentation of [Clock.System] for details.
      *
      * Even though [Instant] is defined to be on the UTC-SLS time scale, which enforces a specific way of handling
      * leap seconds, [now] is not guaranteed to handle leap seconds in any specific way.
@@ -54,6 +54,7 @@ public interface Clock {
         override fun now(): Instant = @Suppress("DEPRECATION_ERROR") Instant.now()
     }
 
+    /** A companion object used purely for namespacing. */
     public companion object {
 
     }

core/common/src/DateTimePeriod.kt

@@ -22,8 +22,8 @@ import kotlinx.serialization.Serializable
  * The time components are: [hours] ([DateTimeUnit.HOUR]), [minutes] ([DateTimeUnit.MINUTE]),
  * [seconds] ([DateTimeUnit.SECOND]), [nanoseconds] ([DateTimeUnit.NANOSECOND]).
  *
- * The time components are not independent and always overflow into one another.
- * Likewise, months overflow into years.
+ * The time components are not independent and are always normalized together.
+ * Likewise, months are normalized together with years.
  * For example, there is no difference between `DateTimePeriod(months = 24, hours = 2, minutes = 63)` and
  * `DateTimePeriod(years = 2, hours = 3, minutes = 3)`.
  *
@@ -73,10 +73,10 @@ public sealed class DateTimePeriod {
     internal abstract val totalMonths: Int
 
     /**
-     * The number of calendar days.
+     * The number of calendar days. Can be negative.
      *
      * Note that a calendar day is not identical to 24 hours, see [DateTimeUnit.DayBased] for details.
-     * Also, this field does not overflow into months, so values larger than 31 can be present.
+     * Also, this field does not get normalized together with months, so values larger than 31 can be present.
      *
      * @sample kotlinx.datetime.test.samples.DateTimePeriodSamples.valueNormalization
      */
@@ -100,7 +100,7 @@ public sealed class DateTimePeriod {
     /**
      * The number of whole hours in this period. Can be negative.
      *
-     * This field does not overflow into days, so values larger than 23 or smaller than -23 can be present.
+     * This field does not get normalized together with days, so values larger than 23 or smaller than -23 can be present.
      *
      * @sample kotlinx.datetime.test.samples.DateTimePeriodSamples.valueNormalization
      */
@@ -210,7 +210,6 @@ public sealed class DateTimePeriod {
          * - Optionally, the number of years, followed by `Y`.
          * - Optionally, the number of months, followed by `M`.
          * - Optionally, the number of weeks, followed by `W`.
-         *   This is not a part of the ISO 8601 format but an extension.
          * - Optionally, the number of days, followed by `D`.
          * - The string can end here if there are no more time components.
          *   If there are time components, the letter `T` is required.

core/common/src/TimeZone.kt

@@ -65,6 +65,8 @@ public expect open class TimeZone {
         /**
          * Returns the time zone with the fixed UTC+0 offset.
          *
+         * The [id] of this time zone is `"UTC"`.
+         *
          * @sample kotlinx.datetime.test.samples.TimeZoneSamples.utc
          */
         public val UTC: FixedOffsetTimeZone

core/common/src/format/DateTimeFormat.kt

@@ -11,6 +11,11 @@ import kotlinx.datetime.internal.format.parser.*
 
 /**
  * A format for parsing and formatting date-time-related values.
+ *
+ * By convention, predefined formats for each applicable class can be found in the `Formats` object of the class, and
+ * custom formats can be created using the `Format` function in the companion object of that class.
+ * For example, [LocalDate.Formats] contains predefined formats for [LocalDate], and [LocalDate.Format] can be used
+ * to define new ones.
  */
 public sealed interface DateTimeFormat<T> {
     /**