Misc docs improvements

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
 

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")
       }

timeline/src/main/kotlin/gov/nasa/jpl/aerie/timeline/BinaryOperation.kt

@@ -58,7 +58,7 @@ fun interface BinaryOperation<in Left, in Right, out Out> {
     }
 
     /**
-     * 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.

timeline/src/main/kotlin/gov/nasa/jpl/aerie/timeline/collections/profiles/Booleans.kt

@@ -24,6 +24,6 @@ data class Booleans(private val timeline: Timeline<Segment<Boolean>, 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<Segment<SerializedValue>>) = Booleans(list.map { it.withNewValue(it.value.asBoolean().get()) })
+    @JvmStatic fun deserialize(list: List<Segment<SerializedValue>>) = Booleans(list.map { it.withNewValue(it.value.asBoolean().get()) })
   }
 }

timeline/src/main/kotlin/gov/nasa/jpl/aerie/timeline/collections/profiles/Constants.kt

@@ -21,11 +21,11 @@ data class Constants<V: Any>(private val timeline: Timeline<Segment<V>, 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<Segment<SerializedValue>>) = Constants(list)
+    @JvmStatic fun deserialize(list: List<Segment<SerializedValue>>) = Constants(list)
   }
 }

timeline/src/main/kotlin/gov/nasa/jpl/aerie/timeline/collections/profiles/Numbers.kt

@@ -39,7 +39,7 @@ data class Numbers<N: Number>(private val timeline: Timeline<Segment<N>, Numbers
      *
      * Prefers converting to longs if possible, and falls back to doubles if not.
      */
-    fun deserialize(list: List<Segment<SerializedValue>>) = Numbers(list.map { seg ->
+    @JvmStatic fun deserialize(list: List<Segment<SerializedValue>>) = Numbers(list.map { seg ->
       val bigDecimal = seg.value.asNumeric().orElseThrow { Exception("value was not numeric: $seg") }
       val number: Number = try {
         bigDecimal.longValueExact()

timeline/src/main/kotlin/gov/nasa/jpl/aerie/timeline/collections/profiles/Real.kt

@@ -32,7 +32,7 @@ data class Real(private val timeline: Timeline<Segment<LinearEquation>, 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<Segment<SerializedValue>>): Real {
+    @JvmStatic fun deserialize(list: List<Segment<SerializedValue>>): Real {
       val converted: List<Segment<LinearEquation>> = 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") }

timeline/src/main/kotlin/gov/nasa/jpl/aerie/timeline/ops/GeneralOps.kt

@@ -30,7 +30,8 @@ interface GeneralOps<V: IntervalLike<V>, THIS: GeneralOps<V, THIS>>: Timeline<V,
    * This function is unsafe because all timeline types have mathematical invariants, such as ordered segments
    * for profiles, and this method allows those invariants to be broken if the user is not careful.
    * In particular, all timelines assume the result of [collect] will be contained in the `bounds` argument.
-   * NONE OF THESE INVARIANTS ARE CHECKED. Violating them is UB. Use at your own risk.
+   * These invariants are often maintained automatically, but you should never assume. Violating them is UB.
+   * Use at your own risk.
    *
    * @param ctor the constructor of the new timeline type
    * @param f a function which, given this and a [CollectOptions] object, produces a list of payload objects

timeline/src/main/kotlin/gov/nasa/jpl/aerie/timeline/ops/SerialOps.kt

@@ -20,7 +20,9 @@ interface SerialOps<V : Any, THIS: SerialOps<V, THIS>>: SegmentOps<V, THIS> {
   infix fun <OTHER: SerialOps<V, OTHER>> zip(other: SerialOps<V, OTHER>) = map2Values(other, BinaryOperation.zip())
 
   /** [(DOC)][assignGaps] Fills in gaps in this profile with another profile. */
-  infix fun <OTHER: SerialOps<V, OTHER>> assignGaps(other: SerialOps<V, OTHER>) = 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 <OTHER: SerialOps<V, OTHER>> assignGaps(other: SerialOps<V, OTHER>) =
+      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))