[orx-noise] Describe ShapeNoise.kt functions (#270)

orx-noise/src/commonMain/kotlin/ShapeNoise.kt

@@ -5,6 +5,10 @@ import org.openrndr.math.Vector2
 import org.openrndr.shape.*
 import kotlin.random.Random
 
+/**
+ * Returns a random [Vector2] point located inside a [ShapeProvider] while
+ * maintaining a distance to the edge of the shape of [distanceToEdge] units.
+ */
 fun ShapeProvider.uniform(distanceToEdge: Double = 0.0, random: Random = Random.Default): Vector2 {
     val shape = shape
     require(!shape.empty)
@@ -20,6 +24,18 @@ fun ShapeProvider.uniform(distanceToEdge: Double = 0.0, random: Random = Random.
     }
 }
 
+/**
+ * Returns a list of pairs in which the first component is a radius and the
+ * second component a list of [Vector2] positions of items with that radius.
+ *
+ * [multiScatter] is a variation of [scatter] not limited to items of equal radius.
+ *
+ * The [radii] argument contains a list of pairs with `placementRadius` and `objectRadius`.
+ *
+ * The algorithm iterates a maximum of [tries] times trying to find 2D points
+ * that maintain the separations to each other specified via [radii] while
+ * keeping a [distanceToEdge] distance to the contour of the shape.
+ */
 fun ShapeProvider.multiScatter(
     radii: List<Pair<Double, Double>>,
     distanceToEdge: Double = 0.0,
@@ -37,7 +53,16 @@ fun ShapeProvider.multiScatter(
     return result
 }
 
-
+/**
+ * Returns a list of 2D points contained in the [ShapeProvider]. The algorithm
+ * iterates a maximum of [tries] times trying to find points that maintain
+ * the separation to each other specified via [placementRadius] while
+ * keeping a [distanceToEdge] distance to the contour of the shape.
+ *
+ * It is possible to include [obstacles] to avoid. The optional
+ * list of obstacles contains pairs, each pair has a radius and a list of
+ * 2D locations. [objectRadius] defines a margin to keep around the obstacles.
+ */
 fun ShapeProvider.scatter(
     placementRadius: Double,
     objectRadius: Double = placementRadius,