From 67316c4a70cee2814ef2e65dece45077bef7c894 Mon Sep 17 00:00:00 2001
From: Alexander Nozik <altavir@gmail.com>
Date: Thu, 16 Feb 2023 10:39:25 +0300
Subject: [PATCH] Add documentation after circle tangent changes

---
 .../kscience/kmath/geometry/GeometrySpace.kt  |  7 ++++
 .../kscience/kmath/geometry/floatPrecision.kt | 32 +++++++++++++++----
 .../kscience/kmath/trajectory/tangent.kt      |  4 +++
 3 files changed, 36 insertions(+), 7 deletions(-)

diff --git a/kmath-geometry/src/commonMain/kotlin/space/kscience/kmath/geometry/GeometrySpace.kt b/kmath-geometry/src/commonMain/kotlin/space/kscience/kmath/geometry/GeometrySpace.kt
index 854d84b65..d6d7e5725 100644
--- a/kmath-geometry/src/commonMain/kotlin/space/kscience/kmath/geometry/GeometrySpace.kt
+++ b/kmath-geometry/src/commonMain/kotlin/space/kscience/kmath/geometry/GeometrySpace.kt
@@ -21,4 +21,11 @@ public interface GeometrySpace<V : Vector> : Group<V>, ScaleOperations<V>, Norm<
      * Scalar product
      */
     public infix fun V.dot(other: V): Double
+
+    public companion object{
+        /**
+         * Default precision for geometry objects comparison
+         */
+        internal const val DEFAULT_PRECISION = 1e-6
+    }
 }
\ No newline at end of file
diff --git a/kmath-geometry/src/commonMain/kotlin/space/kscience/kmath/geometry/floatPrecision.kt b/kmath-geometry/src/commonMain/kotlin/space/kscience/kmath/geometry/floatPrecision.kt
index 023355a0f..ea46ab90f 100644
--- a/kmath-geometry/src/commonMain/kotlin/space/kscience/kmath/geometry/floatPrecision.kt
+++ b/kmath-geometry/src/commonMain/kotlin/space/kscience/kmath/geometry/floatPrecision.kt
@@ -5,34 +5,52 @@
 
 package space.kscience.kmath.geometry
 
-internal const val defaultPrecision = 1e-6
+import space.kscience.kmath.geometry.GeometrySpace.Companion.DEFAULT_PRECISION
 
-public fun Double.equalsFloat(other: Double, precision: Double = defaultPrecision): Boolean =
+/**
+ * Float equality within given [precision]
+ */
+public fun Double.equalsFloat(other: Double, precision: Double = DEFAULT_PRECISION): Boolean =
     kotlin.math.abs(this - other) < precision
 
-public fun Double.equalsFloat(other: Float, precision: Double = defaultPrecision): Boolean =
+/**
+ * Float equality within given [precision]
+ */
+public fun Double.equalsFloat(other: Float, precision: Double = DEFAULT_PRECISION): Boolean =
     kotlin.math.abs(this - other) < precision
 
+/**
+ * Vector equality within given [precision] (using [GeometrySpace.norm] provided by the space
+ */
 public fun <V : Vector> V.equalsVector(
     space: GeometrySpace<V>,
     other: V,
-    precision: Double = defaultPrecision,
+    precision: Double = DEFAULT_PRECISION,
 ): Boolean = with(space) {
     norm(this@equalsVector - other) < precision
 }
 
+/**
+ * Vector equality using Euclidian L2 norm and given [precision]
+ */
 public fun Float64Vector2D.equalsVector(
     other: Float64Vector2D,
-    precision: Double = defaultPrecision,
+    precision: Double = DEFAULT_PRECISION,
 ): Boolean = equalsVector(Euclidean2DSpace, other, precision)
 
+/**
+ * Vector equality using Euclidian L2 norm and given [precision]
+ */
 public fun Float64Vector3D.equalsVector(
     other: Float64Vector3D,
-    precision: Double = defaultPrecision,
+    precision: Double = DEFAULT_PRECISION,
 ): Boolean = equalsVector(Euclidean3DSpace, other, precision)
 
+/**
+ * Line equality using [GeometrySpace.norm] provided by the [space] and given [precision]
+ */
 public fun <V : Vector> LineSegment<V>.equalsLine(
     space: GeometrySpace<V>,
     other: LineSegment<V>,
-    precision: Double = defaultPrecision,
+    precision: Double = DEFAULT_PRECISION,
 ): Boolean = begin.equalsVector(space, other.begin, precision) && end.equalsVector(space, other.end, precision)
\ No newline at end of file
diff --git a/kmath-trajectory/src/commonMain/kotlin/space/kscience/kmath/trajectory/tangent.kt b/kmath-trajectory/src/commonMain/kotlin/space/kscience/kmath/trajectory/tangent.kt
index 70a1ac696..cf5bcd11d 100644
--- a/kmath-trajectory/src/commonMain/kotlin/space/kscience/kmath/trajectory/tangent.kt
+++ b/kmath-trajectory/src/commonMain/kotlin/space/kscience/kmath/trajectory/tangent.kt
@@ -11,6 +11,10 @@ import space.kscience.kmath.geometry.Euclidean2DSpace
 import space.kscience.kmath.geometry.LineSegment
 import kotlin.math.*
 
+/**
+ * Create inner and outer tangents between two circles.
+ * This method returns a map of segments using [DubinsPath] connection type notation.
+ */
 public fun Circle2D.tangentsToCircle(
     other: Circle2D,
 ): Map<DubinsPath.Type, LineSegment<DoubleVector2D>> = with(Euclidean2DSpace) {