Improve the KDoc (#367)

Fixes #347

We methodically went through the complete KDoc-based documentation
and reworked it, adding usage examples, clarifying the specifics
of behaviors, proposing the expected usage patterns, etc.

Additionally, we enabled Dokka's fail-on-warnings flag.

---------

Co-authored-by: Danil.Pavlov <danil.pavlov@jetbrains.com>
Co-authored-by: Vsevolod Tolstopyatov <qwwdfsad@gmail.com>
Co-authored-by: ilya-g <ilya.gorbunov@jetbrains.com>

README.md

@@ -175,7 +175,7 @@ To convert back, use the companion object function `Instant.fromEpochMillisecond
 ### Converting instant and local date/time to and from the ISO 8601 string
 
 `Instant`, `LocalDateTime`, `LocalDate` and `LocalTime` provide shortcuts for
-parsing and formatting them using the extended ISO-8601 format.
+parsing and formatting them using the extended ISO 8601 format.
 The `toString()` function is used to convert the value to a string in that format, and 
 the `parse` function in companion object is used to parse a string representation back. 
 
@@ -201,7 +201,7 @@ LocalTime.parse("12:0:03.999") // fails with an IllegalArgumentException
 
 ### Working with other string formats
 
-When some data needs to be formatted in some format other than ISO-8601, one
+When some data needs to be formatted in some format other than ISO 8601, one
 can define their own format or use some of the predefined ones:
 
 ```kotlin

core/build.gradle.kts

@@ -397,7 +397,9 @@ val downloadWindowsZonesMapping by tasks.registering {
 tasks.withType<AbstractDokkaLeafTask>().configureEach {
     pluginsMapConfiguration.set(mapOf("org.jetbrains.dokka.base.DokkaBase" to """{ "templatesDir" : "${projectDir.toString().replace('\\', '/')}/dokka-templates" }"""))
 
+    failOnWarning.set(true)
     dokkaSourceSets.configureEach {
+        kotlin.sourceSets.commonTest.get().kotlin.srcDirs.forEach { samples.from(it) }
         // reportUndocumented.set(true) // much noisy output about `hashCode` and serializer encoders, decoders etc
         skipDeprecated.set(true)
         // Enum members and undocumented toString()

core/common/src/Clock.kt

@@ -11,33 +11,71 @@ import kotlin.time.*
  * A source of [Instant] values.
  *
  * See [Clock.System][Clock.System] for the clock instance that queries the operating system.
+ *
+ * It is not recommended to use [Clock.System] directly in the implementation. Instead, you can pass a
+ * [Clock] explicitly to the necessary functions or classes.
+ * This way, tests can be written deterministically by providing custom [Clock] implementations
+ * to the system under test.
  */
 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 [Clock.System] it is completely expected that the opposite will happen,
+     * and it must be taken into account.
+     * See the [System] documentation 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.
      */
     public fun now(): Instant
 
     /**
-     * The [Clock] instance that queries the operating system as its source of knowledge of time.
+     * The [Clock] instance that queries the platform-specific system clock as its source of time knowledge.
+     *
+     * Successive calls to [now] will not necessarily return increasing [Instant] values, and when they do,
+     * these increases will not necessarily correspond to the elapsed time.
+     *
+     * For example, when using [Clock.System], the following could happen:
+     * - [now] returns `2023-01-02T22:35:01Z`.
+     * - The system queries the Internet and recognizes that its clock needs adjusting.
+     * - [now] returns `2023-01-02T22:32:05Z`.
+     *
+     * When you need predictable intervals between successive measurements, consider using [TimeSource.Monotonic].
+     *
+     * For improved testability, you should avoid using [Clock.System] directly in the implementation
+     * and pass a [Clock] explicitly instead. For example:
+     *
+     * @sample kotlinx.datetime.test.samples.ClockSamples.system
+     * @sample kotlinx.datetime.test.samples.ClockSamples.dependencyInjection
      */
     public object System : Clock {
         override fun now(): Instant = @Suppress("DEPRECATION_ERROR") Instant.now()
     }
 
+    /** A companion object used purely for namespacing. */
     public companion object {
 
     }
 }
 
 /**
  * Returns the current date at the given [time zone][timeZone], according to [this Clock][this].
+ *
+ * The time zone is important because the current date is not the same in all time zones at the same instant.
+ *
+ * @sample kotlinx.datetime.test.samples.ClockSamples.todayIn
  */
 public fun Clock.todayIn(timeZone: TimeZone): LocalDate =
     now().toLocalDateTime(timeZone).date
 
 /**
  * Returns a [TimeSource] that uses this [Clock] to mark a time instant and to find the amount of time elapsed since that mark.
+ *
+ * **Pitfall**: using this function with [Clock.System] is error-prone
+ * because [Clock.System] is not well suited for measuring time intervals.
+ * Please only use this conversion function on the [Clock] instances that are fully controlled programmatically.
  */
 @ExperimentalTime
 public fun Clock.asTimeSource(): TimeSource.WithComparableMarks = object : TimeSource.WithComparableMarks {