Skip to content

Commit

Permalink
feat: new docs review
Browse files Browse the repository at this point in the history
  • Loading branch information
@danil-pavlov @dkhalanskyjb
danil-pavlov authored and dkhalanskyjb committed Apr 29, 2024
1 parent a2af2de commit f7878af
Show file tree
Hide file tree
Showing 10 changed files with 98 additions and 98 deletions.
19 changes: 9 additions & 10 deletions core/common/src/Clock.kt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,8 +12,8 @@ import kotlin.time.*
*
* See [Clock.System][Clock.System] for the clock instance that queries the operating system.
*
* It is recommended not to use [Clock.System] directly in the implementation; instead, one could pass a
* [Clock] explicitly to the functions or classes that need it.
* 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.
*/
Expand All @@ -24,7 +24,7 @@ public interface 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 documentation of [Clock.System] for details.
* 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.
Expand All @@ -38,15 +38,14 @@ public interface Clock {
* 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:35:01Z`.
* - The system queries the Internet and recognizes that its clock needs adjusting.
* - [now] returns `2023-01-02T22:32:05Z`.
*
* When predictable intervals between successive measurements are needed, consider using
* [TimeSource.Monotonic].
* When you need predictable intervals between successive measurements, consider using [TimeSource.Monotonic].
*
* For improved testability, one could avoid using [Clock.System] directly in the implementation,
* instead passing a [Clock] explicitly. For example:
* 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
Expand Down Expand Up @@ -74,7 +73,7 @@ public fun Clock.todayIn(timeZone: TimeZone): LocalDate =
/**
* 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,
* **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.
*/
Expand Down
6 changes: 3 additions & 3 deletions core/common/src/DateTimePeriod.kt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -17,10 +17,10 @@ import kotlinx.serialization.Serializable
/**
* A difference between two [instants][Instant], decomposed into date and time components.
*
* The date components are: [years] ([DateTimeUnit.YEAR]), [months] ([DateTimeUnit.MONTH]), [days] ([DateTimeUnit.DAY]).
* The date components are: [years] ([DateTimeUnit.YEAR]), [months] ([DateTimeUnit.MONTH]), and [days] ([DateTimeUnit.DAY]).
*
* The time components are: [hours] ([DateTimeUnit.HOUR]), [minutes] ([DateTimeUnit.MINUTE]),
* [seconds] ([DateTimeUnit.SECOND]), [nanoseconds] ([DateTimeUnit.NANOSECOND]).
* [seconds] ([DateTimeUnit.SECOND]), and [nanoseconds] ([DateTimeUnit.NANOSECOND]).
*
* The time components are not independent and are always normalized together.
* Likewise, months are normalized together with years.
Expand Down Expand Up @@ -428,7 +428,7 @@ public class DatePeriod internal constructor(
/**
* Constructs a new [DatePeriod].
*
* It is recommended to always explicitly name the arguments when constructing this manually,
* It is always recommended to name the arguments explicitly when constructing this manually,
* like `DatePeriod(years = 1, months = 12, days = 16)`.
*
* The passed numbers are not stored as is but are normalized instead for human readability, so, for example,
Expand Down
23 changes: 12 additions & 11 deletions core/common/src/DateTimeUnit.kt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,23 +20,23 @@ import kotlin.time.Duration.Companion.nanoseconds
*
* ### Interaction with other entities
*
* Any [DateTimeUnit] can be used with [Instant.plus], [Instant.minus] to
* Any [DateTimeUnit] can be used with [Instant.plus] or [Instant.minus] to
* find an instant that is some number of units away from the given instant.
* Also, [Instant.until] can be used to find the number of the given units between two instants.
*
* [DateTimeUnit.TimeBased] can be used in the [Instant] operations without specifying the time zone, because
* [DateTimeUnit.TimeBased] is defined in terms of passage of real time, and is independent of the time zone.
* [DateTimeUnit.TimeBased] can be used in the [Instant] operations without specifying the time zone because
* [DateTimeUnit.TimeBased] is defined in terms of the passage of real-time and is independent of the time zone.
* Note that a calendar day is not considered identical to 24 hours, so using it does require specifying the time zone.
* See [DateTimeUnit.DayBased] for an explanation.
*
* [DateTimeUnit.DateBased] units can be used in the [LocalDate] operations: [LocalDate.plus], [LocalDate.minus], and
* [LocalDate.until].
*
* Arithmetic operations on [LocalDateTime] are not provided.
* Please see the [LocalDateTime] documentation for a discussion.
* Please see the [LocalDateTime] documentation for details.
*
* [DateTimePeriod] is a combination of [DateTimeUnit] values of every kind, used to express things like
* "two days and three hours."
* [DateTimePeriod] is a combination of [DateTimeUnit] values of every kind, used to express periods like
* "two days and three hours".
* [DatePeriod] is specifically a combination of [DateTimeUnit.DateBased] values.
* [DateTimePeriod] is more flexible than [DateTimeUnit] because it can express a combination of values with different
* kinds of units, but in exchange, the duration of time between two [Instant] or [LocalDate] values can be
Expand All @@ -48,8 +48,8 @@ import kotlin.time.Duration.Companion.nanoseconds
* [DateTimeUnit.MONTH], and others.
*
* Two ways are provided to create custom [DateTimeUnit] instances:
* - By multiplying an existing unit on the right by an integer scalar: for example, `DateTimeUnit.MICROSECOND * 10`.
* - By constructing an instance manually with [TimeBased], [DayBased], or [MonthBased]: for example,
* - By multiplying an existing unit on the right by an integer scalar, for example, `DateTimeUnit.MICROSECOND * 10`.
* - By constructing an instance manually with [TimeBased], [DayBased], or [MonthBased], for example,
* `DateTimeUnit.TimeBased(nanoseconds = 10_000)`.
*
* Also, [DateTimeUnit] can be serialized and deserialized using `kotlinx.serialization`:
Expand Down Expand Up @@ -164,8 +164,8 @@ public sealed class DateTimeUnit {
/**
* A [date-time unit][DateTimeUnit] equal to some number of calendar days.
*
* A calendar day is not considered identical to 24 hours,
* thus a `DayBased`-unit cannot be expressed as a multiple of some [TimeBased]-unit.
* A calendar day is not considered identical to 24 hours.
* Thus, a `DayBased` unit cannot be expressed as a multiple of some [TimeBased] unit.
*
* The reason lies in time zone transitions, because of which some days can be 23 or 25 hours.
* For example, we say that exactly a whole day has passed between `2019-10-27T02:59` and `2019-10-28T02:59`
Expand Down Expand Up @@ -204,7 +204,8 @@ public sealed class DateTimeUnit {
/**
* A [date-time unit][DateTimeUnit] equal to some number of months.
*
* Since different months have different number of days, a `MonthBased`-unit cannot be expressed as a multiple of some [DayBased]-unit.
* Since different months have a different number of days, a `MonthBased` unit cannot be expressed
* as a multiple of some [DayBased]-unit.
*
* @see DateTimeUnit for a description of date-time units in general.
* @sample kotlinx.datetime.test.samples.DateTimeUnitSamples.monthBasedUnit
Expand Down
50 changes: 25 additions & 25 deletions core/common/src/Instant.kt
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,12 +15,12 @@ import kotlin.time.*
/**
* A moment in time.
*
* A point in time must be uniquely identified, so that it is independent of a time zone.
* For example, `1970-01-01, 00:00:00` does not represent a moment in time, since this would happen at different times
* in different time zones: someone in Tokyo would think its already `1970-01-01` several hours earlier than someone in
* A point in time must be uniquely identified so that it is independent of a time zone.
* For example, `1970-01-01, 00:00:00` does not represent a moment in time since this would happen at different times
* in different time zones: someone in Tokyo would think it is already `1970-01-01` several hours earlier than someone in
* Berlin would. To represent such entities, use [LocalDateTime].
* In contrast, "the moment the clocks in London first showed 00:00 on Jan 1, 2000" is a specific moment
* in time, as is "1970-01-01, 00:00:00 UTC+0", and so it can be represented as an [Instant].
* in time, as is "1970-01-01, 00:00:00 UTC+0", so it can be represented as an [Instant].
*
* `Instant` uses the UTC-SLS (smeared leap second) time scale. This time scale doesn't contain instants
* corresponding to leap seconds, but instead "smears" positive and negative leap seconds among the last 1000 seconds
Expand All @@ -46,7 +46,7 @@ import kotlin.time.*
*
* [Instant] is essentially the number of seconds and nanoseconds since a designated moment in time,
* stored as something like `1709898983.123456789`.
* [Instant] contains no information about what day or time it is, as this depends on the time zone.
* [Instant] does not contain information about the day or time, as this depends on the time zone.
* To work with this information for a specific time zone, obtain a [LocalDateTime] using [Instant.toLocalDateTime]:
*
* ```
Expand Down Expand Up @@ -98,16 +98,16 @@ import kotlin.time.*
* Since [Instant] represents a point in time, it is always well-defined what the result of arithmetic operations on it
* is, including the cases when a calendar is used.
* This is not the case for [LocalDateTime], where the result of arithmetic operations depends on the time zone.
* See the documentation of [LocalDateTime] for more details.
* See the [LocalDateTime] documentation for more details.
*
* Adding and subtracting calendar-based units can be done using the [plus] and [minus] operators,
* requiring a [TimeZone]:
*
* ```
* // one day from now in Berlin
* // One day from now in Berlin
* Clock.System.now().plus(1, DateTimeUnit.DAY, TimeZone.of("Europe/Berlin"))
*
* // a day and two hours short from two months later in Berlin
* // A day and two hours short from two months later in Berlin
* Clock.System.now().plus(DateTimePeriod(months = 2, days = -1, hours = -2), TimeZone.of("Europe/Berlin"))
* ```
*
Expand All @@ -118,7 +118,7 @@ import kotlin.time.*
* val start = Clock.System.now()
* val concertStart = LocalDateTime(2023, 1, 1, 20, 0, 0).toInstant(TimeZone.of("Europe/Berlin"))
* val timeUntilConcert = start.periodUntil(concertStart, TimeZone.of("Europe/Berlin"))
* // two months, three days, four hours, and five minutes until the concert
* // Two months, three days, four hours, and five minutes until the concert
* ```
*
* or [Instant.until] method, as well as [Instant.daysUntil], [Instant.monthsUntil],
Expand Down Expand Up @@ -187,7 +187,7 @@ import kotlin.time.*
* ```
*
* Additionally, there are several `kotlinx-serialization` serializers for [Instant]:
* - [InstantIso8601Serializer] for the ISO 8601 extended format,
* - [InstantIso8601Serializer] for the ISO 8601 extended format.
* - [InstantComponentSerializer] for an object with components.
*
* @see LocalDateTime for a user-visible representation of moments in time in an unspecified time zone.
Expand Down Expand Up @@ -285,7 +285,7 @@ public expect class Instant : Comparable<Instant> {

/**
* Compares `this` instant with the [other] instant.
* Returns zero if this instant represents the same moment as the other (i.e., equal to other),
* Returns zero if this instant represents the same moment as the other (i.e., when it's equal to other),
* a negative number if this instant is earlier than the other,
* and a positive number if this instant is later than the other.
*
Expand All @@ -294,9 +294,9 @@ public expect class Instant : Comparable<Instant> {
public override operator fun compareTo(other: Instant): Int

/**
* Converts this instant to the ISO 8601 string representation; for example, `2023-01-02T23:40:57.120Z`
* Converts this instant to the ISO 8601 string representation, for example, `2023-01-02T23:40:57.120Z`.
*
* The representation uses the UTC-SLS time scale, instead of UTC.
* The representation uses the UTC-SLS time scale instead of UTC.
* In practice, this means that leap second handling will not be readjusted to the UTC.
* Leap seconds will not be added or skipped, so it is impossible to acquire a string
* where the component for seconds is 60, and for any day, it's possible to observe 23:59:59.
Expand Down Expand Up @@ -480,9 +480,9 @@ public fun Instant.minus(period: DateTimePeriod, timeZone: TimeZone): Instant =
* The components of [DateTimePeriod] are calculated so that adding it to `this` instant results in the [other] instant.
*
* All components of the [DateTimePeriod] returned are:
* - positive or zero if this instant is earlier than the other,
* - negative or zero if this instant is later than the other,
* - exactly zero if this instant is equal to the other.
* - Positive or zero if this instant is earlier than the other.
* - Negative or zero if this instant is later than the other.
* - Exactly zero if this instant is equal to the other.
*
* @throws DateTimeArithmeticException if `this` or [other] instant is too large to fit in [LocalDateTime].
* Or (only on the JVM) if the number of months between the two dates exceeds an Int.
Expand All @@ -495,9 +495,9 @@ public expect fun Instant.periodUntil(other: Instant, timeZone: TimeZone): DateT
* in the specified [timeZone].
*
* The value returned is:
* - positive or zero if this instant is earlier than the other,
* - negative or zero if this instant is later than the other,
* - zero if this instant is equal to the other.
* - Positive or zero if this instant is earlier than the other.
* - Negative or zero if this instant is later than the other.
* - Zero if this instant is equal to the other.
*
* If the result does not fit in [Long], returns [Long.MAX_VALUE] for a positive result or [Long.MIN_VALUE] for a negative result.
*
Expand All @@ -510,9 +510,9 @@ public expect fun Instant.until(other: Instant, unit: DateTimeUnit, timeZone: Ti
* Returns the whole number of the specified time [units][unit] between `this` and [other] instants.
*
* The value returned is:
* - positive or zero if this instant is earlier than the other,
* - negative or zero if this instant is later than the other,
* - zero if this instant is equal to the other.
* - Positive or zero if this instant is earlier than the other.
* - Negative or zero if this instant is later than the other.
* - Zero if this instant is equal to the other.
*
* If the result does not fit in [Long], returns [Long.MAX_VALUE] for a positive result or [Long.MIN_VALUE] for a negative result.
*
Expand Down Expand Up @@ -570,9 +570,9 @@ public fun Instant.yearsUntil(other: Instant, timeZone: TimeZone): Int =
* The components of [DateTimePeriod] are calculated so that adding it back to the `other` instant results in this instant.
*
* All components of the [DateTimePeriod] returned are:
* - negative or zero if this instant is earlier than the other,
* - positive or zero if this instant is later than the other,
* - exactly zero if this instant is equal to the other.
* - Negative or zero if this instant is earlier than the other.
* - Positive or zero if this instant is later than the other.
* - Exactly zero if this instant is equal to the other.
*
* @throws DateTimeArithmeticException if `this` or [other] instant is too large to fit in [LocalDateTime].
* Or (only on the JVM) if the number of months between the two dates exceeds an Int.
Expand Down
Loading

0 comments on commit f7878af

Please sign in to comment.