Massive reworking of documentation production.

wiring.scad

@@ -1,5 +1,10 @@
 //////////////////////////////////////////////////////////////////////
-// Rendering for wiring bundles
+// LibFile: wiring.scad
+//   Rendering for wiring bundles
+//   To use, include the following line at the top of your file:
+//   ```
+//   use <BOSL/wiring.scad>
+//   ```
 //////////////////////////////////////////////////////////////////////
 
 /*
@@ -36,43 +41,73 @@ include <paths.scad>
 include <beziers.scad>
 
 
-// Returns an array of 1 or 6 points that form a ring, based on wire diam and ring level.
-// Level 0 returns a single point at 0,0.  All greater levels return 6 points.
-function hex_offset_ring(wirediam, lev=0) =
+// Section: Functions
+
+
+// Function: hex_offset_ring()
+// Description:
+//   Returns a hexagonal ring of points, with a spacing of `d`.
+//   If `lev=0`, returns a single point at `[0,0]`.  All greater
+//   levels return 6 times `lev` points.
+// Usage:
+//   hex_offset_ring(d, lev)
+// Arguments:
+//   d = Base unit diameter to build rings upon.
+//   lev = How many rings to produce.
+// Example:
+//   hex_offset_ring(d=1, lev=3); // Returns a hex ring of 18 points.
+function hex_offset_ring(d, lev=0) =
 	(lev == 0)? [[0,0]] : [
 		for (
 			sideang = [0:60:359.999],
-			sidewire = [1:lev]
+			sidenum = [1:lev]
 		) [
-			lev*wirediam*cos(sideang)+sidewire*wirediam*cos(sideang+120),
-			lev*wirediam*sin(sideang)+sidewire*wirediam*sin(sideang+120)
+			lev*d*cos(sideang)+sidenum*d*cos(sideang+120),
+			lev*d*sin(sideang)+sidenum*d*sin(sideang+120)
 		]
 	];
 
 
-// Returns an array of 2D centerpoints for each of a bundle of wires of given diameter.
-// The lev and arr variables are used for internal recursion.
-function hex_offsets(wires, wirediam, lev=0, arr=[]) =
-	(len(arr) >= wires)? arr :
+// Function: hex_offsets()
+// Description:
+//   Returns the centerpoints for the optimal hexagonal packing
+//   of at least `n` circular items, of diameter `d`.  Will return
+//   enough points to fill out the last ring, even if that is more
+//   than `n` points.
+// Usage:
+//   hex_offsets(n, d)
+// Arguments:
+//   n = Number of items to bundle.
+//   d = How far to space each point away from others.
+function hex_offsets(n, d, lev=0, arr=[]) =
+	(len(arr) >= n)? arr :
 		hex_offsets(
-			wires=wires,
-			wirediam=wirediam,
+			n=n,
+			d=d,
 			lev=lev+1,
-			arr=concat(arr, hex_offset_ring(wirediam, lev=lev))
+			arr=concat(arr, hex_offset_ring(d, lev=lev))
 		);
 
 
-// Returns a 3D object representing a bundle of wires that follow a given path,
-// with the corners filleted to a given radius.  There are 17 base wire colors.
-// If you have more than 17 wires, colors will get re-used.
-// Arguments:
-//   path:     The 3D polyline path that the wire bundle should follow.
-//   wires:    The number of wires in the wiring bundle.
-//   wirediam: The diameter of each wire in the bundle.
-//   fillet:   The radius that the path corners will be filleted to.
-//   wirenum:  The first wire's offset into the color table.
-//   bezsteps: The corner fillets in the path will be converted into this number of segments.
+
+// Section: Modules
+
+
+// Module: wiring()
+// Description:
+//   Returns a 3D object representing a bundle of wires that follow a given path,
+//   with the corners filleted to a given radius.  There are 17 base wire colors.
+//   If you have more than 17 wires, colors will get re-used.
 // Usage:
+//   wiring(path, wires, [wirediam], [fillet], [wirenum], [bezsteps]);
+// Arguments:
+//   path = The 3D polyline path that the wire bundle should follow.
+//   wires = The number of wires in the wiring bundle.
+//   wirediam = The diameter of each wire in the bundle.
+//   fillet = The radius that the path corners will be filleted to.
+//   wirenum = The first wire's offset into the color table.
+//   bezsteps = The corner fillets in the path will be converted into this number of segments.
+// Example:
 //   wiring([[50,0,-50], [50,50,-50], [0,50,-50], [0,0,-50], [0,0,0]], fillet=10, wires=13);
 module wiring(path, wires, wirediam=2, fillet=10, wirenum=0, bezsteps=12) {
 	colors = [