From 5b5190409c4c113a5bf8d9b916c1c9335ab16758 Mon Sep 17 00:00:00 2001 From: JoelCourtney Date: Wed, 28 Feb 2024 14:09:48 -0800 Subject: [PATCH] Misc docs improvements --- timeline/MODULE_DOCS.md | 4 +++- timeline/build.gradle | 8 ++++---- .../kotlin/gov/nasa/jpl/aerie/timeline/BinaryOperation.kt | 2 +- .../jpl/aerie/timeline/collections/profiles/Booleans.kt | 2 +- .../jpl/aerie/timeline/collections/profiles/Constants.kt | 4 ++-- .../jpl/aerie/timeline/collections/profiles/Numbers.kt | 2 +- .../nasa/jpl/aerie/timeline/collections/profiles/Real.kt | 2 +- .../kotlin/gov/nasa/jpl/aerie/timeline/ops/GeneralOps.kt | 3 ++- .../kotlin/gov/nasa/jpl/aerie/timeline/ops/SerialOps.kt | 4 +++- 9 files changed, 18 insertions(+), 13 deletions(-) diff --git a/timeline/MODULE_DOCS.md b/timeline/MODULE_DOCS.md index e8d899f518..a35bfc3aef 100644 --- a/timeline/MODULE_DOCS.md +++ b/timeline/MODULE_DOCS.md @@ -60,7 +60,9 @@ val segments = shifted.collect(CollectOptions( When `shifted`'s collector is invoked, it will in turn invoke `original'`s collector - but not on the same bounds. Instead, the bounds will be `Interval.between(-HOUR, DAY - HOUR)`. It is one hour earlier so that objects in `original` just before the intended bounds of `[ZERO, DAY]` are properly calculated and shifted into the bounds. -Similarly, some operations can change whether marginal objects are truncated. `GeneralOps.filterByDuration` and `NonZeroDurationOps.split` will always perform their call the previous timeline's collector with `truncateMarginal = false`, because they need to know the full duration of all objects. (They will then truncate the marginal objects in the result if it was requested in `CollectOptions`.) +Similarly, some operations can change whether marginal objects are truncated. `GeneralOps.filterByDuration` and `NonZeroDurationOps.split` will always perform their call the previous timeline's collector with `truncateMarginal = false`, because they need to know the full duration of all objects. (They will then truncate the marginal objects in the result if it was requested in `CollectOptions`.) Unfortunately, this is not totally fool-proof; if an +operation is applied to a profile that would have caused a segment fully outside the bounds to be coalesced (see below) +with a marginal segment, the full extent of the segment will be lost. ### Coalescing diff --git a/timeline/build.gradle b/timeline/build.gradle index 46d701c5d2..478ff92968 100644 --- a/timeline/build.gradle +++ b/timeline/build.gradle @@ -21,7 +21,7 @@ dependencies { testImplementation 'org.jetbrains.kotlin:kotlin-test-junit5' testRuntimeOnly("org.junit.platform:junit-platform-launcher") - dokkaHtmlPlugin 'org.jetbrains.dokka:kotlin-as-java-plugin:1.9.10' +// dokkaHtmlPlugin 'org.jetbrains.dokka:kotlin-as-java-plugin:1.9.10' } tasks.withType(KotlinJvmCompile.class).configureEach { @@ -50,10 +50,10 @@ dokkaHtml.configure { // adds source links that lead to this repository, allowing readers // to easily find source code for inspected declarations - sourceLink { - localDirectory.set(file("src/main/kotlin")) + sourceLink.configure { + localDirectory.set(file("timeline/src/main/kotlin")) remoteUrl.set(URL( - "https://github.com/NASA-AMMOS/aerie/tree/feat/java-timeline-library/timeline/src/main/kotlin" + "https://github.com/NASA-AMMOS/aerie/blob/feat/java-timeline-library/timeline/src/main/kotlin" )) remoteLineSuffix.set("#L") } diff --git a/timeline/src/main/kotlin/gov/nasa/jpl/aerie/timeline/BinaryOperation.kt b/timeline/src/main/kotlin/gov/nasa/jpl/aerie/timeline/BinaryOperation.kt index 0fd7c8e644..504f9ec2b4 100644 --- a/timeline/src/main/kotlin/gov/nasa/jpl/aerie/timeline/BinaryOperation.kt +++ b/timeline/src/main/kotlin/gov/nasa/jpl/aerie/timeline/BinaryOperation.kt @@ -58,7 +58,7 @@ fun interface BinaryOperation { } /** - * Constructs an operation that combines the operands OF EQUAL TYPE if they are both present. + * Constructs an operation that combines the operands of equal type if they are both present. * If either operand is not present, the other is passed through unchanged. * * This means that both operands and the output must all be the same type. diff --git a/timeline/src/main/kotlin/gov/nasa/jpl/aerie/timeline/collections/profiles/Booleans.kt b/timeline/src/main/kotlin/gov/nasa/jpl/aerie/timeline/collections/profiles/Booleans.kt index 0210f6d401..0bbb1e8a15 100644 --- a/timeline/src/main/kotlin/gov/nasa/jpl/aerie/timeline/collections/profiles/Booleans.kt +++ b/timeline/src/main/kotlin/gov/nasa/jpl/aerie/timeline/collections/profiles/Booleans.kt @@ -24,6 +24,6 @@ data class Booleans(private val timeline: Timeline, Booleans>): * Converts a list of serialized value segments into a [Booleans] profile; * for use with [gov.nasa.jpl.aerie.timeline.plan.Plan.resource]. */ - fun deserialize(list: List>) = Booleans(list.map { it.withNewValue(it.value.asBoolean().get()) }) + @JvmStatic fun deserialize(list: List>) = Booleans(list.map { it.withNewValue(it.value.asBoolean().get()) }) } } diff --git a/timeline/src/main/kotlin/gov/nasa/jpl/aerie/timeline/collections/profiles/Constants.kt b/timeline/src/main/kotlin/gov/nasa/jpl/aerie/timeline/collections/profiles/Constants.kt index c786d5d3fd..029e81751d 100644 --- a/timeline/src/main/kotlin/gov/nasa/jpl/aerie/timeline/collections/profiles/Constants.kt +++ b/timeline/src/main/kotlin/gov/nasa/jpl/aerie/timeline/collections/profiles/Constants.kt @@ -21,11 +21,11 @@ data class Constants(private val timeline: Timeline, Constant /***/ companion object { /** - * Delegates to the constructor, * for use with [gov.nasa.jpl.aerie.timeline.plan.Plan.resource]. + * Delegates to the constructor, for use with [gov.nasa.jpl.aerie.timeline.plan.Plan.resource]. * * Does not convert the serialized values because it does not know what it should be converted into. * You will need to do that yourself using [mapValues]. */ - fun deserialize(list: List>) = Constants(list) + @JvmStatic fun deserialize(list: List>) = Constants(list) } } diff --git a/timeline/src/main/kotlin/gov/nasa/jpl/aerie/timeline/collections/profiles/Numbers.kt b/timeline/src/main/kotlin/gov/nasa/jpl/aerie/timeline/collections/profiles/Numbers.kt index 98d73ff8aa..90857c7e0f 100644 --- a/timeline/src/main/kotlin/gov/nasa/jpl/aerie/timeline/collections/profiles/Numbers.kt +++ b/timeline/src/main/kotlin/gov/nasa/jpl/aerie/timeline/collections/profiles/Numbers.kt @@ -39,7 +39,7 @@ data class Numbers(private val timeline: Timeline, Numbers * * Prefers converting to longs if possible, and falls back to doubles if not. */ - fun deserialize(list: List>) = Numbers(list.map { seg -> + @JvmStatic fun deserialize(list: List>) = Numbers(list.map { seg -> val bigDecimal = seg.value.asNumeric().orElseThrow { Exception("value was not numeric: $seg") } val number: Number = try { bigDecimal.longValueExact() diff --git a/timeline/src/main/kotlin/gov/nasa/jpl/aerie/timeline/collections/profiles/Real.kt b/timeline/src/main/kotlin/gov/nasa/jpl/aerie/timeline/collections/profiles/Real.kt index 719b14fc95..e903afdbab 100644 --- a/timeline/src/main/kotlin/gov/nasa/jpl/aerie/timeline/collections/profiles/Real.kt +++ b/timeline/src/main/kotlin/gov/nasa/jpl/aerie/timeline/collections/profiles/Real.kt @@ -32,7 +32,7 @@ data class Real(private val timeline: Timeline, Real>): * While plain numbers are acceptable and will be converted to a [LinearEquation] without warning, consider using [Numbers] * to keep the precision. */ - fun deserialize(list: List>): Real { + @JvmStatic fun deserialize(list: List>): Real { val converted: List> = list.map { s -> s.value.asReal().getOrNull()?.let { return@map s.withNewValue(LinearEquation(it)) } val map = s.value.asMap().orElseThrow { RealDeserializeException("value was not a map or plain number: $s") } diff --git a/timeline/src/main/kotlin/gov/nasa/jpl/aerie/timeline/ops/GeneralOps.kt b/timeline/src/main/kotlin/gov/nasa/jpl/aerie/timeline/ops/GeneralOps.kt index 3c3ef59040..c7c3f7fb56 100644 --- a/timeline/src/main/kotlin/gov/nasa/jpl/aerie/timeline/ops/GeneralOps.kt +++ b/timeline/src/main/kotlin/gov/nasa/jpl/aerie/timeline/ops/GeneralOps.kt @@ -30,7 +30,8 @@ interface GeneralOps, THIS: GeneralOps>: Timeline>: SegmentOps { infix fun > zip(other: SerialOps) = map2Values(other, BinaryOperation.zip()) /** [(DOC)][assignGaps] Fills in gaps in this profile with another profile. */ - infix fun > assignGaps(other: SerialOps) = other.set(this) + // While this is logically the converse of [set], they can't delegate to each other because it would mess up the return type. + infix fun > assignGaps(other: SerialOps) = + map2Values(other, BinaryOperation.combineOrIdentity { l, _, _, -> l }) /** [(DOC)][assignGaps] Fills in gaps in this profile with a constant value. */ infix fun assignGaps(v: V) = assignGaps(Constants(v))