diff --git a/orx-shapes/src/jvmDemo/kotlin/hobbycurve/DemoHobbyCurve01.kt b/orx-shapes/src/jvmDemo/kotlin/hobbycurve/DemoHobbyCurve01.kt
index fa407fa4..5393976e 100644
--- a/orx-shapes/src/jvmDemo/kotlin/hobbycurve/DemoHobbyCurve01.kt
+++ b/orx-shapes/src/jvmDemo/kotlin/hobbycurve/DemoHobbyCurve01.kt
@@ -8,6 +8,8 @@ import org.openrndr.math.Vector2
 /**
  * Demonstrates how to use the hobbyCurve function to render a smooth closed contour
  * passing through a predefined set of points.
+ *
+ * See Hobby, John. D., “Smooth, Easy to Compute Interpolating Splines”, Discrete and Computational Geometry, 1986, vol. 1
  */
 fun main() = application {
     program {
diff --git a/orx-shapes/src/jvmDemo/kotlin/hobbycurve/DemoHobbyCurve3D01.kt b/orx-shapes/src/jvmDemo/kotlin/hobbycurve/DemoHobbyCurve3D01.kt
index 09948d0d..2a621b33 100644
--- a/orx-shapes/src/jvmDemo/kotlin/hobbycurve/DemoHobbyCurve3D01.kt
+++ b/orx-shapes/src/jvmDemo/kotlin/hobbycurve/DemoHobbyCurve3D01.kt
@@ -11,6 +11,20 @@ import org.openrndr.math.Vector3
 import kotlin.math.cos
 import kotlin.random.Random
 
+/**
+ * Demonstrates how to use the 3D implementation of the `hobbyCurve` method, to draw a smooth curve passing
+ * through various 3D points in space.
+ *
+ * The program first creates a random set of 2D points at least 200 pixels away from the window borders.
+ *
+ * Then, on every animation frame, it recreates a 3D hobby curve by giving depth to each 2D point.
+ * The same seed is used for randomness, so the same depths are assigned on every animation frame, although
+ * varying tensions are applied to each segment, based on cosines of the current time in seconds.
+ *
+ * Commenting out the camera rotation (`camera.rotate`) reveals how the segment tensions change over time.
+ *
+ * The last few lines of the program enable a rotating 3D camera and draw the 3D path.
+ */
 fun main() = application {
     configure {
         width = 720
diff --git a/orx-shapes/src/jvmDemo/kotlin/operators/DemoRoundCorners01.kt b/orx-shapes/src/jvmDemo/kotlin/operators/DemoRoundCorners01.kt
index aa002b81..cf004765 100644
--- a/orx-shapes/src/jvmDemo/kotlin/operators/DemoRoundCorners01.kt
+++ b/orx-shapes/src/jvmDemo/kotlin/operators/DemoRoundCorners01.kt
@@ -5,6 +5,13 @@ import org.openrndr.color.ColorRGBa
 import org.openrndr.extra.shapes.operators.roundCorners
 import org.openrndr.extra.shapes.primitives.regularStar
 
+/**
+ * Demonstrates how to use the `roundCorners` method to round the sharp corners
+ * of a [org.openrndr.shape.ShapeContour] made out of linear segments.
+ *
+ * The program creates a regular start with 7 points, then draws 7 variations
+ * of this star with various levels of rounding.
+ */
 fun main() = application {
     configure {
         width = 720
diff --git a/orx-shapes/src/jvmDemo/kotlin/operators/DemoRoundCorners02.kt b/orx-shapes/src/jvmDemo/kotlin/operators/DemoRoundCorners02.kt
index 99b4ed49..c9324eb8 100644
--- a/orx-shapes/src/jvmDemo/kotlin/operators/DemoRoundCorners02.kt
+++ b/orx-shapes/src/jvmDemo/kotlin/operators/DemoRoundCorners02.kt
@@ -5,6 +5,18 @@ import org.openrndr.extra.shapes.adjust.adjustContour
 import org.openrndr.extra.shapes.operators.roundCorners
 import org.openrndr.shape.Rectangle
 
+/**
+ * Demonstrates how, with the current implementation of `roundCorners`, only pairs of consecutive linear segments
+ * are rounded. If one of the segments in the pair is a quadratic or cubic Bezier, no rounding is applied.
+ *
+ * The program creates a list with two rectangular contours. In the second of them a vertex is rotated,
+ * causing two segments to become curved.
+ *
+ * Next, rounded versions of both contours are stored in a new list.
+ *
+ * Finally, all 4 shapes are displayed for comparison.
+ *
+ */
 fun main() = application {
     program {
         extend {
diff --git a/orx-shapes/src/jvmDemo/kotlin/ordering/DemoHilbertOrder01.kt b/orx-shapes/src/jvmDemo/kotlin/ordering/DemoHilbertOrder01.kt
index 9efd1343..fceeb435 100644
--- a/orx-shapes/src/jvmDemo/kotlin/ordering/DemoHilbertOrder01.kt
+++ b/orx-shapes/src/jvmDemo/kotlin/ordering/DemoHilbertOrder01.kt
@@ -6,6 +6,17 @@ import org.openrndr.extra.noise.uniform
 import org.openrndr.extra.shapes.ordering.hilbertOrder
 import kotlin.random.Random
 
+/**
+ * Demonstrates the use of the `hilbertOrder` method to sort 2D points in a list of random points.
+ *
+ * When drawing the sorted points as a line strip, this line crosses itself fewer times than if the
+ * points were drawn in a random order (sometimes zero crossings, depending on the number and layout of the points).
+ *
+ * The Hilbert curve (also known as the Hilbert space-filling curve) is a continuous fractal
+ * space-filling curve first described by the German mathematician David Hilbert in 1891
+ * https://en.wikipedia.org/wiki/Hilbert_curve
+ *
+ */
 fun main() = application {
     configure {
         width = 720
diff --git a/orx-shapes/src/jvmDemo/kotlin/ordering/DemoHilbertOrder02.kt b/orx-shapes/src/jvmDemo/kotlin/ordering/DemoHilbertOrder02.kt
index 5bb6275a..b4a6dbbb 100644
--- a/orx-shapes/src/jvmDemo/kotlin/ordering/DemoHilbertOrder02.kt
+++ b/orx-shapes/src/jvmDemo/kotlin/ordering/DemoHilbertOrder02.kt
@@ -6,6 +6,16 @@ import org.openrndr.extra.noise.uniform
 import org.openrndr.extra.shapes.ordering.hilbertOrder
 import kotlin.random.Random
 
+/**
+ * Shows the difference between sorting the same random points in 2D (in red) and in 3D (in blue).
+ *
+ * To be able to sort the points in 3D, the 2D points are temporarily converted to 3D with 0.0 as the `z` component,
+ * sorted, then converted back to 2D discarding the `z` component.
+ *
+ * Try out the alternative `mortonOrder` as well.
+ *
+ * Note that the `bits` argument can be either 5 or 16 in 2D, and 5 or 10 in 3D, other values are not supported.
+ */
 fun main() = application {
     configure {
         width = 720
diff --git a/orx-shapes/src/jvmDemo/kotlin/path3d/DemoPath3DProjection.kt b/orx-shapes/src/jvmDemo/kotlin/path3d/DemoPath3DProjection.kt
index 86ed8f9a..35ab6332 100644
--- a/orx-shapes/src/jvmDemo/kotlin/path3d/DemoPath3DProjection.kt
+++ b/orx-shapes/src/jvmDemo/kotlin/path3d/DemoPath3DProjection.kt
@@ -7,8 +7,17 @@ import org.openrndr.extra.camera.Orbital
 import org.openrndr.extra.shapes.path3d.projectToContour
 import org.openrndr.math.Spherical
 import org.openrndr.math.Vector3
+import org.openrndr.shape.ShapeContour
 import org.openrndr.shape.path3D
 
+/**
+ * Demonstrates how to convert a 3D path as seen by an [Orbital] camera to a 2D [ShapeContour].
+ *
+ * Among other uses, this can be useful when working with pen plotters,
+ * to export a 3D path to an SVG file, or to apply 2D contour post-processing with
+ * [org.openrndr.extra.shapes.adjust.adjustContour].
+ *
+ */
 fun main() = application {
     program {
         val path = path3D {
diff --git a/orx-shapes/src/jvmDemo/kotlin/primitives/DemoArc01.kt b/orx-shapes/src/jvmDemo/kotlin/primitives/DemoArc01.kt
index 0e75a844..83a664ae 100644
--- a/orx-shapes/src/jvmDemo/kotlin/primitives/DemoArc01.kt
+++ b/orx-shapes/src/jvmDemo/kotlin/primitives/DemoArc01.kt
@@ -4,6 +4,16 @@ import org.openrndr.application
 import org.openrndr.color.ColorRGBa
 import org.openrndr.extra.shapes.primitives.Arc
 
+/**
+ * Shows how to create an `Arc` centered on the window. The start and end angles of the arc increase 36 degrees
+ * per second, resulting in an animated effect.
+ *
+ * The `contour` property of the arc is used for rendering.
+ *
+ * The start, mid and end points of the arc are queried using it's `position()` method
+ * to draw small circles at those locations.
+ *
+ */
 fun main() = application {
     configure {
         width = 720
diff --git a/orx-shapes/src/jvmDemo/kotlin/primitives/DemoNet01.kt b/orx-shapes/src/jvmDemo/kotlin/primitives/DemoNet01.kt
index f29b16b8..92c875b1 100644
--- a/orx-shapes/src/jvmDemo/kotlin/primitives/DemoNet01.kt
+++ b/orx-shapes/src/jvmDemo/kotlin/primitives/DemoNet01.kt
@@ -6,6 +6,16 @@ import org.openrndr.extra.shapes.primitives.Net
 import org.openrndr.shape.Circle
 import kotlin.math.sin
 
+/**
+ * Shows how to create and render a [Net]: a structure
+ * that connects two points with a circle in between,
+ * forming a string-like shape.
+ *
+ * The main circle moves following an invisible infinite sign,
+ * formed by a pair of sine functions. The moving circle is connected to
+ * two smaller static circles via a [Net], rendered as a white
+ * contour with a stroke weight 2 pixels wide.
+ */
 fun main() = application {
     program {
         extend {
diff --git a/orx-shapes/src/jvmDemo/kotlin/primitives/DemoPulley01.kt b/orx-shapes/src/jvmDemo/kotlin/primitives/DemoPulley01.kt
index ad58dba2..77f08f7f 100644
--- a/orx-shapes/src/jvmDemo/kotlin/primitives/DemoPulley01.kt
+++ b/orx-shapes/src/jvmDemo/kotlin/primitives/DemoPulley01.kt
@@ -6,6 +6,10 @@ import org.openrndr.extra.shapes.primitives.Pulley
 import org.openrndr.math.Vector2
 import org.openrndr.shape.Circle
 
+/**
+ * Demonstrates how to create and render a [Pulley]: a system defined by two circles
+ * connected by their outer tangents.
+ */
 fun main() = application {
     configure {
         width = 720
@@ -14,6 +18,7 @@ fun main() = application {
     program {
         extend {
             drawer.clear(ColorRGBa.BLACK)
+            drawer.strokeWeight = 8.0
             drawer.stroke = ColorRGBa.WHITE
             drawer.fill = ColorRGBa.PINK
             val pulley = Pulley(
diff --git a/orx-shapes/src/jvmDemo/kotlin/text/DemoText01.kt b/orx-shapes/src/jvmDemo/kotlin/text/DemoText01.kt
index f610986a..1509738c 100644
--- a/orx-shapes/src/jvmDemo/kotlin/text/DemoText01.kt
+++ b/orx-shapes/src/jvmDemo/kotlin/text/DemoText01.kt
@@ -7,6 +7,15 @@ import org.openrndr.extra.camera.Camera2D
 import org.openrndr.extra.shapes.bounds.bounds
 import org.openrndr.extra.shapes.text.shapesFromText
 
+/**
+ * Demonstrates how to create vector-based shapes based on a font face file, a text and a size.
+ *
+ * Try to zoom and pan with the 2D camera to verify that the text is actually rendered as vectors.
+ *
+ * [shapesFromText] returns a `List<Shape>`, where each letter is an element in that list,
+ * making it possible to style or manipulate each letter independently.
+ *
+ */
 fun main() = application {
     configure {
         width = 720