From 55b7ffdfb31e650d1143422b6a457ba16734aeed Mon Sep 17 00:00:00 2001
From: Edwin Jakobs <edwin@rndr.studio>
Date: Sat, 18 Jan 2025 23:21:48 +0100
Subject: [PATCH] [orx-kdtree] Add generated and verified documentation

---
 orx-kdtree/src/commonMain/kotlin/QuickSelect.kt     | 11 +++++++++++
 .../src/jvmDemo/kotlin/DemoKNearestNeighbour01.kt   | 12 ++++++++++++
 .../src/jvmDemo/kotlin/DemoNearestNeighbour01.kt    | 12 ++++++++++++
 orx-kdtree/src/jvmDemo/kotlin/DemoRangeQuery01.kt   | 13 +++++++++++++
 4 files changed, 48 insertions(+)

diff --git a/orx-kdtree/src/commonMain/kotlin/QuickSelect.kt b/orx-kdtree/src/commonMain/kotlin/QuickSelect.kt
index e5ed77503..88c152989 100644
--- a/orx-kdtree/src/commonMain/kotlin/QuickSelect.kt
+++ b/orx-kdtree/src/commonMain/kotlin/QuickSelect.kt
@@ -1,5 +1,16 @@
 package org.openrndr.extra.kdtree
 
+/**
+ * Selects the nth element from the given list after partially sorting it based on a mapping function.
+ *
+ * This method modifies the input list to reorder its elements such that the nth element is placed
+ * at the correct sorted position if the list were fully sorted according to the provided mapper.
+ *
+ * @param items The list of elements to process and partially sort.
+ * @param n The zero-based index of the element to select after partial sorting.
+ * @param mapper A lambda function that maps an element of type T to a Double, used to determine sorting order.
+ * @return The nth element in the reordered list.
+ */
 fun <T> selectNth(items: MutableList<T>, n: Int, mapper: (T)->Double): T {
     var from = 0
     var to = items.size - 1
diff --git a/orx-kdtree/src/jvmDemo/kotlin/DemoKNearestNeighbour01.kt b/orx-kdtree/src/jvmDemo/kotlin/DemoKNearestNeighbour01.kt
index 4fbc44d79..a95909e5a 100644
--- a/orx-kdtree/src/jvmDemo/kotlin/DemoKNearestNeighbour01.kt
+++ b/orx-kdtree/src/jvmDemo/kotlin/DemoKNearestNeighbour01.kt
@@ -4,6 +4,18 @@ import org.openrndr.extra.kdtree.kdTree
 import org.openrndr.math.Vector2
 import org.openrndr.shape.LineSegment
 
+/**
+ * This demo initializes an interactive graphical application where 1000 randomly distributed points
+ * are displayed on a 2D canvas. A KD-tree structure is used for spatial querying of the points, enabling
+ * efficient nearest-neighbor searches based on the user's cursor position. The closest 7 points to the
+ * cursor are highlighted with circles and lines connecting them to the cursor.
+ *
+ * Key features:
+ * - Generates 1000 random 2D points within the canvas dimensions (1080x720).
+ * - Builds a KD-tree from the list of points for optimized spatial querying.
+ * - Visualizes the points and highlights the 7 nearest neighbors to the user's cursor position dynamically.
+ * - Highlights include red-colored circles around the nearest points and red lines connecting them to the cursor.
+ */
 fun main() {
     application {
         configure {
diff --git a/orx-kdtree/src/jvmDemo/kotlin/DemoNearestNeighbour01.kt b/orx-kdtree/src/jvmDemo/kotlin/DemoNearestNeighbour01.kt
index 418d2a326..5470e3c15 100644
--- a/orx-kdtree/src/jvmDemo/kotlin/DemoNearestNeighbour01.kt
+++ b/orx-kdtree/src/jvmDemo/kotlin/DemoNearestNeighbour01.kt
@@ -2,6 +2,18 @@ import org.openrndr.application
 import org.openrndr.extra.kdtree.kdTree
 import org.openrndr.math.Vector2
 
+/**
+ * Initializes an interactive graphical application that displays 1000 randomly distributed 2D points
+ * on a canvas of dimensions 1280x720. The points are organized into a KD-tree for efficient spatial querying.
+ *
+ * Key functionality:
+ * - Displays the points as small circles on the canvas.
+ * - Dynamically highlights the nearest point to the cursor's position by drawing a larger circle around it.
+ *
+ * Highlights:
+ * - KD-tree structure enables efficient nearest-neighbor searches.
+ * - The nearest point to the cursor is determined and visually emphasized in real-time as the cursor moves.
+ */
 fun main() {
     application {
         configure {
diff --git a/orx-kdtree/src/jvmDemo/kotlin/DemoRangeQuery01.kt b/orx-kdtree/src/jvmDemo/kotlin/DemoRangeQuery01.kt
index 9a8b5834c..bada40a36 100644
--- a/orx-kdtree/src/jvmDemo/kotlin/DemoRangeQuery01.kt
+++ b/orx-kdtree/src/jvmDemo/kotlin/DemoRangeQuery01.kt
@@ -4,6 +4,19 @@ import org.openrndr.extra.kdtree.kdTree
 import org.openrndr.math.Vector2
 
 
+/**
+ * Initializes an interactive graphical application that demonstrates spatial querying with KD-trees.
+ * A canvas is populated with 1000 randomly distributed 2D points, and a KD-tree is used for efficient
+ * spatial operations. The program dynamically highlights points within a specified radius from the
+ * user's cursor position.
+ *
+ * Key features:
+ * - Generates and displays 1000 random 2D points within canvas dimensions of 1080x720.
+ * - Builds a KD-tree structure for optimized querying of spatial data.
+ * - Dynamically highlights points within a specified radius (50.0) from the cursor position.
+ * - Visualizes the current query radius around the cursor as an outline circle.
+ * - Uses different fill and stroke styles to distinguish highlighted points and query visuals.
+ */
 fun main() {
     application {