Skip to content

Improve the KDoc #367

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 35 commits into from
May 13, 2024
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
35 commits
Select commit Hold shift + click to select a range
b6a6338
Improve the KDoc
dkhalanskyjb Mar 12, 2024
0a7298e
Fix typos and small mistakes
dkhalanskyjb Mar 18, 2024
e076439
Don't hyphenate ISO 8601 when used as a compound adjective
dkhalanskyjb Mar 21, 2024
ca9c739
Implement the first pack of fixes after the review
dkhalanskyjb Mar 21, 2024
c6dd47f
The second pack of changes
dkhalanskyjb Mar 22, 2024
1a4b0f9
Add samples for TimeZone, UtcOffset, and Month
dkhalanskyjb Apr 3, 2024
6883ffb
WIP: add samples for LocalTime
dkhalanskyjb Apr 4, 2024
671ee59
WIP: add samples for some formatting APIs
dkhalanskyjb Apr 5, 2024
bca9eab
More samples
dkhalanskyjb Apr 15, 2024
ba55ab6
Add samples for format builders
dkhalanskyjb Apr 15, 2024
85ab102
Samples for Date(Time)Period and Clock
dkhalanskyjb Apr 16, 2024
cccad01
fixup
dkhalanskyjb Apr 16, 2024
f3d4653
More samples; only LocalDate and Instant left
dkhalanskyjb Apr 16, 2024
77aff41
Samples for LocalDate
dkhalanskyjb Apr 16, 2024
d70657b
Finish adding samples
dkhalanskyjb Apr 17, 2024
3c956e0
Address the reviews
dkhalanskyjb Apr 17, 2024
788285c
Try to find the edge cases that work across platforms
dkhalanskyjb Apr 17, 2024
60ed765
reword
dkhalanskyjb Apr 17, 2024
fd8be7d
Update core/common/src/DateTimeUnit.kt
dkhalanskyjb Apr 19, 2024
1302b7e
Address the comments
dkhalanskyjb Apr 19, 2024
8f73a08
Clarify setting DateTimeComponents.month
dkhalanskyjb Apr 19, 2024
33a3717
Provide a one-line description for every sample
dkhalanskyjb Apr 19, 2024
a2af2de
More additions according to the reviews
dkhalanskyjb Apr 19, 2024
f7878af
feat: new docs review
danil-pavlov Apr 12, 2024
63644e6
Mention the relevant parts of ISO 8601 when describing formats
dkhalanskyjb Apr 30, 2024
e6b758e
Incorporate some more proofreading results
dkhalanskyjb Apr 30, 2024
517ae7a
Address the review
dkhalanskyjb May 1, 2024
f45e493
Address the review
dkhalanskyjb May 3, 2024
8a0e356
~fixup
dkhalanskyjb May 8, 2024
f70e422
Remove separate samples for Long overloads (plus a small fixup)
dkhalanskyjb May 10, 2024
6c1423a
Use yyyy instead of uuuu in the Unicode pattern sample
dkhalanskyjb May 10, 2024
fa59e05
Use Instant.fromEpochSeconds in samples more
dkhalanskyjb May 10, 2024
a529d44
Fix a broken sample reference
dkhalanskyjb May 10, 2024
a0a1335
Fix broken table rendering
dkhalanskyjb May 10, 2024
8851274
Properly display samples in Dokka
dkhalanskyjb May 10, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Don't hyphenate ISO 8601 when used as a compound adjective
  • Loading branch information
dkhalanskyjb committed Apr 29, 2024
commit e076439431d01a931f24a02373cb870be2841bfc
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand All @@ -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
Expand Down
8 changes: 4 additions & 4 deletions core/common/src/DateTimePeriod.kt
Original file line number Diff line number Diff line change
Expand Up @@ -96,7 +96,7 @@ public sealed class DateTimePeriod {
totalMonths <= 0 && days <= 0 && totalNanoseconds <= 0 && (totalMonths or days != 0 || totalNanoseconds != 0L)

/**
* Converts this period to the ISO-8601 string representation for durations, for example, `P2M1DT3H`.
* Converts this period to the ISO 8601 string representation for durations, for example, `P2M1DT3H`.
*
* @see DateTimePeriod.parse
*/
Expand Down Expand Up @@ -143,12 +143,12 @@ public sealed class DateTimePeriod {

public companion object {
/**
* Parses a ISO-8601 duration string as a [DateTimePeriod].
* Parses a ISO 8601 duration string as a [DateTimePeriod].
* If the time components are absent or equal to zero, returns a [DatePeriod].
*
* Additionally, we support the `W` signifier to represent weeks.
*
* Examples of durations in the ISO-8601 format:
* Examples of durations in the ISO 8601 format:
* - `P1Y40D` is one year and 40 days
* - `-P1DT1H` is minus (one day and one hour)
* - `P1DT-1H` is one day minus one hour
Expand Down Expand Up @@ -372,7 +372,7 @@ public class DatePeriod internal constructor(

public companion object {
/**
* Parses the ISO-8601 duration representation as a [DatePeriod], for example, `P1Y2M30D`.
* Parses the ISO 8601 duration representation as a [DatePeriod], for example, `P1Y2M30D`.
*
* This function is equivalent to [DateTimePeriod.parse], but will fail if any of the time components are not
* zero.
Expand Down
4 changes: 2 additions & 2 deletions core/common/src/DayOfWeek.kt
Original file line number Diff line number Diff line change
Expand Up @@ -22,12 +22,12 @@ public expect enum class DayOfWeek {
}

/**
* The ISO-8601 number of the given day of the week. Monday is 1, Sunday is 7.
* The ISO 8601 number of the given day of the week. Monday is 1, Sunday is 7.
*/
public val DayOfWeek.isoDayNumber: Int get() = ordinal + 1

/**
* Returns the [DayOfWeek] instance for the given ISO-8601 week day number. Monday is 1, Sunday is 7.
* Returns the [DayOfWeek] instance for the given ISO 8601 week day number. Monday is 1, Sunday is 7.
*/
public fun DayOfWeek(isoDayNumber: Int): DayOfWeek {
require(isoDayNumber in 1..7) { "Expected ISO day-of-week number in 1..7, got $isoDayNumber" }
Expand Down
2 changes: 1 addition & 1 deletion core/common/src/Instant.kt
Original file line number Diff line number Diff line change
Expand Up @@ -240,7 +240,7 @@ 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.
* In practice, this means that leap second handling will not be readjusted to the UTC.
Expand Down
2 changes: 1 addition & 1 deletion core/common/src/LocalDate.kt
Original file line number Diff line number Diff line change
Expand Up @@ -200,7 +200,7 @@ public expect class LocalDate : Comparable<LocalDate> {
public override fun compareTo(other: LocalDate): Int

/**
* Converts this date to the extended ISO-8601 string representation.
* Converts this date to the extended ISO 8601 string representation.
*
* @see Formats.ISO for the format details.
* @see parse for the dual operation: obtaining [LocalDate] from a string.
Expand Down
2 changes: 1 addition & 1 deletion core/common/src/LocalTime.kt
Original file line number Diff line number Diff line change
Expand Up @@ -264,7 +264,7 @@ public expect class LocalTime : Comparable<LocalTime> {
public override operator fun compareTo(other: LocalTime): Int

/**
* Converts this time value to the extended ISO-8601 string representation.
* Converts this time value to the extended ISO 8601 string representation.
*
* For readability, if the time represents a round minute (without seconds or fractional seconds),
* the string representation will not include seconds. Also, fractions of seconds will add trailing zeros to
Expand Down
2 changes: 1 addition & 1 deletion core/common/src/UtcOffset.kt
Original file line number Diff line number Diff line change
Expand Up @@ -158,7 +158,7 @@ public expect class UtcOffset {
}

/**
* Converts this UTC offset to the extended ISO-8601 string representation; for example, `+02:30` or `Z`.
* Converts this UTC offset to the extended ISO 8601 string representation; for example, `+02:30` or `Z`.
*
* @see Formats.ISO for the format details.
* @see parse for the dual operation: obtaining [UtcOffset] from a string.
Expand Down
4 changes: 2 additions & 2 deletions core/common/src/serializers/DateTimePeriodSerializers.kt
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ public object DateTimePeriodComponentSerializer: KSerializer<DateTimePeriod> {
}

/**
* A serializer for [DateTimePeriod] that represents it as an ISO-8601 duration string.
* A serializer for [DateTimePeriod] that represents it as an ISO 8601 duration string.
*
* JSON example: `"P1DT-1H"`
*
Expand Down Expand Up @@ -154,7 +154,7 @@ public object DatePeriodComponentSerializer: KSerializer<DatePeriod> {
}

/**
* A serializer for [DatePeriod] that represents it as an ISO-8601 duration string.
* A serializer for [DatePeriod] that represents it as an ISO 8601 duration string.
*
* Deserializes the time components as well, as long as they are zero.
*
Expand Down
2 changes: 1 addition & 1 deletion core/common/src/serializers/InstantSerializers.kt
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ import kotlinx.serialization.descriptors.*
import kotlinx.serialization.encoding.*

/**
* A serializer for [Instant] that uses the ISO-8601 representation.
* A serializer for [Instant] that uses the ISO 8601 representation.
*
* JSON example: `"2020-12-09T09:16:56.000124Z"`
*
Expand Down
2 changes: 1 addition & 1 deletion core/common/src/serializers/LocalDateSerializers.kt
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ import kotlinx.serialization.descriptors.*
import kotlinx.serialization.encoding.*

/**
* A serializer for [LocalDate] that uses the ISO-8601 representation.
* A serializer for [LocalDate] that uses the ISO 8601 representation.
*
* JSON example: `"2020-01-01"`
*
Expand Down
2 changes: 1 addition & 1 deletion core/common/src/serializers/LocalDateTimeSerializers.kt
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ import kotlinx.serialization.descriptors.*
import kotlinx.serialization.encoding.*

/**
* A serializer for [LocalDateTime] that uses the ISO-8601 representation.
* A serializer for [LocalDateTime] that uses the ISO 8601 representation.
*
* JSON example: `"2007-12-31T23:59:01"`
*
Expand Down
2 changes: 1 addition & 1 deletion core/common/src/serializers/LocalTimeSerializers.kt
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ import kotlinx.serialization.descriptors.*
import kotlinx.serialization.encoding.*

/**
* A serializer for [LocalTime] that uses the ISO-8601 representation.
* A serializer for [LocalTime] that uses the ISO 8601 representation.
*
* JSON example: `"12:01:03.999"`
*
Expand Down
2 changes: 1 addition & 1 deletion core/common/src/serializers/TimeZoneSerializers.kt
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ public object FixedOffsetTimeZoneSerializer: KSerializer<FixedOffsetTimeZone> {
}

/**
* A serializer for [UtcOffset] that uses the extended ISO-8601 representation.
* A serializer for [UtcOffset] that uses the extended ISO 8601 representation.
*
* JSON example: `"+02:00"`
*
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -117,7 +117,7 @@ class DateTimePeriodSerializationTest {

@Test
fun testDefaultSerializers() {
// Check that they behave the same as the ISO-8601 serializers
// Check that they behave the same as the ISO 8601 serializers
dateTimePeriodIso8601Serialization(Json.serializersModule.serializer())
datePeriodIso8601Serialization(Json.serializersModule.serializer(), Json.serializersModule.serializer())
}
Expand Down
4 changes: 2 additions & 2 deletions serialization/common/test/InstantSerializationTest.kt
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,7 @@ class InstantSerializationTest {

@Test
fun testDefaultSerializers() {
// should be the same as the ISO-8601
// should be the same as the ISO 8601
iso8601Serialization(Json.serializersModule.serializer())
}
}
}
2 changes: 1 addition & 1 deletion serialization/common/test/LocalDateSerializationTest.kt
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ class LocalDateSerializationTest {

@Test
fun testDefaultSerializers() {
// should be the same as the ISO-8601
// should be the same as the ISO 8601
iso8601Serialization(Json.serializersModule.serializer())
}

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -79,7 +79,7 @@ class LocalDateTimeSerializationTest {

@Test
fun testDefaultSerializers() {
// should be the same as the ISO-8601
// should be the same as the ISO 8601
iso8601Serialization(Json.serializersModule.serializer())
}
}
2 changes: 1 addition & 1 deletion serialization/common/test/LocalTimeSerializationTest.kt
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@ class LocalTimeSerializationTest {

@Test
fun testDefaultSerializers() {
// should be the same as the ISO-8601
// should be the same as the ISO 8601
iso8601Serialization(Json.serializersModule.serializer())
}
}