Merge branch 'master' of github.com:revarbat/BOSL2 into revarbat_dev

attachments.scad

@@ -390,7 +390,7 @@ _ANCHOR_TYPES = ["intersect","hull"];
 
 // Module: position()
 // Usage:
-//   position(from) {...}
+//   position(from) CHILDREN;
 //
 // Topics: Attachments
 // See Also: attachable(), attach(), orient()
@@ -408,6 +408,7 @@ _ANCHOR_TYPES = ["intersect","hull"];
 //   }
 module position(from)
 {
+    req_children($children);
     assert($parent_geom != undef, "No object to attach to!");
     anchors = (is_vector(from)||is_string(from))? [from] : from;
     for (anchr = anchors) {
@@ -422,8 +423,8 @@ module position(from)
 
 // Module: orient()
 // Usage:
-//   orient(dir, <spin=>) ...
+//   orient(dir, [spin=]) CHILDREN;
-//   orient(anchor=, <spin=>) ...
+//   orient(anchor=, [spin=]) CHILDREN;
 // Topics: Attachments
 // Description:
 //   Orients children such that their top is tilted towards the given direction, or towards the
@@ -460,6 +461,7 @@ module position(from)
 //               prismoid([30,30],[0,5],h=20,anchor=BOT+BACK);
 //   }
 module orient(dir, anchor, spin) {
+    req_children($children);
     if (!is_undef(dir)) {
         assert(anchor==undef, "Only one of dir= or anchor= may be given to orient()");
         assert(is_vector(dir));
@@ -486,11 +488,10 @@ module orient(dir, anchor, spin) {
 
 
 
-
 // Module: attach()
 // Usage:
-//   attach(from, [overlap=], [norot=]) {...}
+//   attach(from, [overlap=], [norot=]) CHILDREN;
-//   attach(from, to, [overlap=], [norot=]) {...}
+//   attach(from, to, [overlap=], [norot=]) CHILDREN;
 // Topics: Attachments
 // See Also: attachable(), position(), face_profile(), edge_profile(), corner_profile()
 // Description:
@@ -514,6 +515,7 @@ module orient(dir, anchor, spin) {
 //   }
 module attach(from, to, overlap, norot=false)
 {
+    req_children($children);
     assert($parent_geom != undef, "No object to attach to!");
     overlap = (overlap!=undef)? overlap : $overlap;
     anchors = (is_vector(from)||is_string(from))? [from] : from;
@@ -537,7 +539,7 @@ module attach(from, to, overlap, norot=false)
 
 // Module: tags()
 // Usage:
-//   tags(tags) {...}
+//   tags(tags) CHILDREN;
 // Topics: Attachments
 // See Also: force_tags(), recolor(), hide(), show(), diff(), intersect()
 // Description:
@@ -560,6 +562,7 @@ module attach(from, to, overlap, norot=false)
 //     }  
 module tags(tags)
 {
+    req_children($children);
     $tags = tags;
     children();
 }
@@ -567,7 +570,7 @@ module tags(tags)
 
 // Module: force_tags()
 // Usage:
-//   force_tags([tags]) {...}
+//   force_tags([tags]) CHILDREN;
 // Topics: Attachments
 // See Also: tags(), recolor(), hide(), show(), diff(), intersect()
 // Description:
@@ -609,6 +612,7 @@ module tags(tags)
 //   }
 module force_tags(tags)
 {
+    req_children($children);
     $tags = is_def(tags) ? tags : $tags;
     if(_attachment_is_shown($tags)) {
         children();
@@ -618,7 +622,7 @@ module force_tags(tags)
 
 // Module: diff()
 // Usage:
-//   diff(neg, [keep]) {...}
+//   diff(neg, [keep]) CHILDREN;
 // Topics: Attachments
 // See Also: tags(), recolor(), show(), hide(), intersect()
 // Description:
@@ -706,6 +710,7 @@ module force_tags(tags)
 //       }
 module diff(neg, keep)
 {
+    req_children($children);
     // Don't perform the operation if the current tags are hidden
     if (_attachment_is_shown($tags)) {
         difference() {
@@ -725,14 +730,14 @@ module diff(neg, keep)
 
 // Module: intersect()
 // Usage:
-//   intersect(a, [keep=]) {...}
+//   intersect(a, [keep=]) CHILDREN;
-//   intersect(a, b, [keep=]) {...}
+//   intersect(a, b, [keep=]) CHILDREN;
 // Topics: Attachments
 // See Also: tags(), recolor(), show(), hide(), diff()
 // Description:
-//   If `a` is given, takes the union of all children with tags that are in `a`, and `intersection()`s
+//   If `a` is given, takes the union of all children with tags that are in `a`, and intersects
 //   them with the union of all children with tags in `b`.  If `b` is not given, then the union of all
-//   items with tags in `a` are intersection()ed with the union of all items without tags in `a`.  If
+//   items with tags in `a` are intersected with the union of all items without tags in `a`.  If
 //   `keep` is given, then the result is unioned with all the children with tags in `keep`.  If `keep`
 //   is not given, all children without tags in `a` or `b` are unioned with the result.
 //   Cannot be used in conjunction with `diff()` or `hulling()` on the same parent object.
@@ -764,6 +769,7 @@ module diff(neg, keep)
 //   }
 module intersect(a, b=undef, keep=undef)
 {
+    req_children($children);
     // Don't perform the operation if the current tags are hidden
     if (_attachment_is_shown($tags)) {
         intersection() {
@@ -790,7 +796,7 @@ module intersect(a, b=undef, keep=undef)
 
 // Module: hulling()
 // Usage:
-//   hulling(a) {...}
+//   hulling(a) CHILDREN;
 // Topics: Attachments
 // See Also: tags(), recolor(), show(), hide(), diff(), intersect()
 // Description:
@@ -810,6 +816,7 @@ module intersect(a, b=undef, keep=undef)
 //   }
 module hulling(a)
 {
+    req_children($children);
     if (is_undef(a)) {
         hull() children();
     } else {
@@ -821,7 +828,7 @@ module hulling(a)
 
 // Module: hide()
 // Usage:
-//   hide(tags) {...}
+//   hide(tags) CHILDREN;
 // Topics: Attachments
 // See Also: tags(), recolor(), show(), diff(), intersect()
 // Description:
@@ -834,6 +841,7 @@ module hulling(a)
 //   }
 module hide(tags="")
 {
+    req_children($children);
     $tags_hidden = tags==""? [] : str_split(tags, " ");
     $tags_shown = [];
     children();
@@ -842,7 +850,7 @@ module hide(tags="")
 
 // Module: show()
 // Usage:
-//   show(tags) {...}
+//   show(tags) CHILDREN;
 // Topics: Attachments
 // See Also: tags(), recolor(), hide(), diff(), intersect()
 // Description:
@@ -855,6 +863,7 @@ module hide(tags="")
 //   }
 module show(tags="")
 {
+    req_children($children);
     $tags_shown = tags==""? [] : str_split(tags, " ");
     $tags_hidden = [];
     children();
@@ -867,7 +876,7 @@ module show(tags="")
 
 // Module: edge_mask()
 // Usage:
-//   edge_mask([edges], [except]) {...}
+//   edge_mask([edges], [except]) CHILDREN;
 // Topics: Attachments
 // See Also: attachable(), position(), attach(), face_profile(), edge_profile(), corner_mask()
 // Description:
@@ -895,6 +904,7 @@ module show(tags="")
 //       edge_mask([TOP,"Z"],except=[BACK,TOP+LEFT])
 //           rounding_edge_mask(l=71,r=10);
 module edge_mask(edges=EDGES_ALL, except=[]) {
+    req_children($children);
     assert($parent_geom != undef, "No object to attach to!");
     edges = _edges(edges, except=except);
     vecs = [
@@ -922,7 +932,7 @@ module edge_mask(edges=EDGES_ALL, except=[]) {
 
 // Module: corner_mask()
 // Usage:
-//   corner_mask([corners], [except]) {...}
+//   corner_mask([corners], [except]) CHILDREN;
 // Topics: Attachments
 // See Also: attachable(), position(), attach(), face_profile(), edge_profile(), edge_mask()
 // Description:
@@ -944,6 +954,7 @@ module edge_mask(edges=EDGES_ALL, except=[]) {
 //               translate([20,20,20]) sphere(r=20);
 //           }
 module corner_mask(corners=CORNERS_ALL, except=[]) {
+    req_children($children);
     assert($parent_geom != undef, "No object to attach to!");
     corners = _corners(corners, except=except);
     vecs = [for (i = [0:7]) if (corners[i]>0) CORNER_OFFSETS[i]];
@@ -965,7 +976,7 @@ module corner_mask(corners=CORNERS_ALL, except=[]) {
 
 // Module: face_profile()
 // Usage:
-//   face_profile(faces, r|d=, [convexity=]) {...}
+//   face_profile(faces, r|d=, [convexity=]) CHILDREN;
 // Topics: Attachments
 // See Also: attachable(), position(), attach(), edge_profile(), corner_profile()
 // Description:
@@ -986,6 +997,7 @@ module corner_mask(corners=CORNERS_ALL, except=[]) {
 //       face_profile(TOP,r=10)
 //           mask2d_roundover(r=10);
 module face_profile(faces=[], r, d, convexity=10) {
+    req_children($children);
     faces = is_vector(faces)? [faces] : faces;
     assert(all([for (face=faces) is_vector(face) && sum([for (x=face) x!=0? 1 : 0])==1]), "Vector in faces doesn't point at a face.");
     r = get_radius(r=r, d=d, dflt=undef);
@@ -997,7 +1009,7 @@ module face_profile(faces=[], r, d, convexity=10) {
 
 // Module: edge_profile()
 // Usage:
-//   edge_profile([edges], [except], [convexity]) {...}
+//   edge_profile([edges], [except], [convexity]) CHILDREN;
 // Topics: Attachments
 // See Also: attachable(), position(), attach(), face_profile(), corner_profile()
 // Description:
@@ -1018,6 +1030,7 @@ module face_profile(faces=[], r, d, convexity=10) {
 //       edge_profile([TOP,"Z"],except=[BACK,TOP+LEFT])
 //           mask2d_roundover(r=10, inset=2);
 module edge_profile(edges=EDGES_ALL, except=[], convexity=10) {
+    req_children($children);
     assert($parent_geom != undef, "No object to attach to!");
     edges = _edges(edges, except=except);
     vecs = [
@@ -1052,7 +1065,7 @@ module edge_profile(edges=EDGES_ALL, except=[], convexity=10) {
 
 // Module: corner_profile()
 // Usage:
-//   corner_profile([corners], [except], <r=|d=>, [convexity=]) {...}
+//   corner_profile([corners], [except], [r=|d=], [convexity=]) CHILDREN;
 // Topics: Attachments
 // See Also: attachable(), position(), attach(), face_profile(), edge_profile()
 // Description:
@@ -1121,33 +1134,33 @@ module corner_profile(corners=CORNERS_ALL, except=[], r, d, convexity=10) {
 // Module: attachable()
 //
 // Usage: Square/Trapezoid Geometry
-//   attachable(anchor, spin, two_d=true, size=, [size2=], [shift=], ...) {...}
+//   attachable(anchor, spin, two_d=true, size=, [size2=], [shift=], ...) {OBJECT; children();}
 // Usage: Circle/Oval Geometry
-//   attachable(anchor, spin, two_d=true, r=|d=, ...) {...}
+//   attachable(anchor, spin, two_d=true, r=|d=, ...) {OBJECT; children();}
 // Usage: 2D Path/Polygon Geometry
-//   attachable(anchor, spin, two_d=true, path=, [extent=], ...) {...}
+//   attachable(anchor, spin, two_d=true, path=, [extent=], ...) {OBJECT; children();}
 // Usage: 2D Region Geometry
-//   attachable(anchor, spin, two_d=true, region=, [extent=], ...) {...}
+//   attachable(anchor, spin, two_d=true, region=, [extent=], ...) {OBJECT; children();}
 // Usage: Cubical/Prismoidal Geometry
-//   attachable(anchor, spin, [orient], size=, [size2=], [shift=], ...) {...}
+//   attachable(anchor, spin, [orient], size=, [size2=], [shift=], ...) {OBJECT; children();}
 // Usage: Cylindrical Geometry
-//   attachable(anchor, spin, [orient], r=|d=, l=, [axis=], ...) {...}
+//   attachable(anchor, spin, [orient], r=|d=, l=, [axis=], ...) {OBJECT; children();}
 // Usage: Conical Geometry
-//   attachable(anchor, spin, [orient], r1=|d1=, r2=|d2=, l=, [axis=], ...) {...}
+//   attachable(anchor, spin, [orient], r1=|d1=, r2=|d2=, l=, [axis=], ...) {OBJECT; children();}
 // Usage: Spheroid/Ovoid Geometry
-//   attachable(anchor, spin, [orient], r=|d=, ...) {...}
+//   attachable(anchor, spin, [orient], r=|d=, ...) {OBJECT; children();}
 // Usage: Extruded Path/Polygon Geometry
-//   attachable(anchor, spin, path=, l=|h=, [extent=], ...) {...}
+//   attachable(anchor, spin, path=, l=|h=, [extent=], ...) {OBJECT; children();}
 // Usage: Extruded Region Geometry
-//   attachable(anchor, spin, region=, l=|h=, [extent=], ...) {...}
+//   attachable(anchor, spin, region=, l=|h=, [extent=], ...) {OBJECT; children();}
 // Usage: VNF Geometry
-//   attachable(anchor, spin, [orient], vnf=, [extent=], ...) {...}
+//   attachable(anchor, spin, [orient], vnf=, [extent=], ...) {OBJECT; children();}
 //
 // Topics: Attachments
 // See Also: reorient()
 //
 // Description:
-//   Manages the anchoring, spin, orientation, and attachments for a 3D volume or 2D area.
+//   Manages the anchoring, spin, orientation, and attachments for OBJECT, located in a 3D volume or 2D area.
 //   A managed 3D volume is assumed to be vertically (Z-axis) oriented, and centered.
 //   A managed 2D area is just assumed to be centered.  The shape to be managed is given
 //   as the first child to this module, and the second child should be given as `children()`.

beziers.scad

@@ -371,7 +371,7 @@ function bezier_length(bezier, start_u=0, end_u=1, max_deflect=0.01) =
 
 // Function: bezier_line_intersection()
 // Usage: 
-//   u = bezier_line_intersection(curve, line);
+//   u = bezier_line_intersection(bezier, line);
 // Topics: Bezier Curves, Geometry, Intersection
 // See Also: bezier_points(), bezier_length(), bezier_closest_point()
 // Description:
@@ -708,6 +708,7 @@ function bezpath_offset(offset, bezier, N=3) =
 //   pt = The starting endpoint for the bezier path.
 //   a = If given a scalar, specifies the theta (XY plane) angle in degrees from X+.  If given a vector, specifies the direction and possibly distance of the first control point.
 //   r = Specifies the distance of the control point from the endpoint `pt`.
+//   ---
 //   p = If given, specifies the number of degrees away from the Z+ axis.
 // Example(2D): 2D Bezier Path by Angle
 //   bezpath = flatten([
@@ -781,6 +782,7 @@ function bez_begin(pt,a,r,p) =
 //   a = If given a scalar, specifies the theta (XY plane) angle in degrees from X+.  If given a vector, specifies the direction and possibly distance of the departing control point.
 //   r1 = Specifies the distance of the approching control point from the fixed point.  Overrides the distance component of the vector if `a` contains a vector.
 //   r2 = Specifies the distance of the departing control point from the fixed point.  Overrides the distance component of the vector if `a` contains a vector.  If `r1` is given and `r2` is not, uses the value of `r1` for `r2`.
+//   ---
 //   p = If given, specifies the number of degrees away from the Z+ axis.
 function bez_tang(pt,a,r1,r2,p) =
     assert(is_finite(r1) || is_vector(a))
@@ -816,6 +818,7 @@ function bez_tang(pt,a,r1,r2,p) =
 //   a2 = If given a scalar, specifies the theta (XY plane) angle in degrees from X+.  If given a vector, specifies the direction and possibly distance of the departing control point.
 //   r1 = Specifies the distance of the approching control point from the fixed point.  Overrides the distance component of the vector if `a1` contains a vector.
 //   r2 = Specifies the distance of the departing control point from the fixed point.  Overrides the distance component of the vector if `a2` contains a vector.
+//   ---
 //   p1 = If given, specifies the number of degrees away from the Z+ axis of the approaching control point.
 //   p2 = If given, specifies the number of degrees away from the Z+ axis of the departing control point.
 function bez_joint(pt,a1,a2,r1,r2,p1,p2) =

color.scad

@@ -15,7 +15,7 @@ use <builtins.scad>
 
 // Module: recolor()
 // Usage:
-//   recolor([c]) children;
+//   recolor([c]) CHILDREN;
 // Topics: Attachments
 // See Also: color_this()
 // Description:
@@ -42,7 +42,7 @@ module recolor(c="default")
 
 // Module: color_this()
 // Usage:
-//   color_this([c]) children;
+//   color_this([c]) CHILDREN;
 // Topics: Attachments
 // See Also: recolor()
 // Description:
@@ -71,7 +71,7 @@ module color_this(c="default")
 
 // Module: rainbow()
 // Usage:
-//   rainbow(list,[stride],[maxhues],[shuffle],[seed]) children;
+//   rainbow(list,[stride],[maxhues],[shuffle],[seed]) CHILDREN;
 // Description:
 //   Iterates the list, displaying children in different colors for each list item.  The color
 //   is set using the color() module, so this module is not compatible with {{recolor()}} or
@@ -110,7 +110,7 @@ module rainbow(list, stride=1, maxhues, shuffle=false, seed)
 
 // Function&Module: hsl()
 // Usage:
-//   hsl(h,[s],[l],[a]) children;
+//   hsl(h,[s],[l],[a]) CHILDREN;
 //   rgb = hsl(h,[s],[l],[a]);
 // Description:
 //   When called as a function, returns the [R,G,B] color for the given hue `h`, saturation `s`, and lightness `l` from the HSL colorspace. If you supply
@@ -145,7 +145,7 @@ module hsl(h,s=1,l=0.5,a=1)
 
 // Function&Module: hsv()
 // Usage:
-//   hsv(h,[s],[v],[a]) children;
+//   hsv(h,[s],[v],[a]) CHILDREN;
 //   rgb = hsv(h,[s],[v],[a]);
 // Description:
 //   When called as a function, returns the [R,G,B] color for the given hue `h`, saturation `s`, and value `v` from the HSV colorspace.  If you supply

distributors.scad

@@ -20,7 +20,7 @@
 //   Translates copies of all children to each given translation offset.
 //
 // Usage:
-//   move_copies(a) children;
+//   move_copies(a) CHILDREN;
 //
 // Arguments:
 //   a = Array of XYZ offset vectors. Default `[[0,0,0]]`
@@ -47,15 +47,15 @@ module move_copies(a=[[0,0,0]])
 // Function&Module: line_of()
 //
 // Usage: Spread `n` copies by a given spacing
-//   line_of(spacing, [n], [p1=]) children;
+//   line_of(spacing, [n], [p1=]) CHILDREN;
 // Usage: Spread copies every given spacing along the line
-//   line_of(spacing, [l=], [p1=]) children;
+//   line_of(spacing, [l=], [p1=]) CHILDREN;
 // Usage: Spread `n` copies along the length of the line
-//   line_of([n=], [l=], [p1=]) children;
+//   line_of([n=], [l=], [p1=]) CHILDREN;
 // Usage: Spread `n` copies along the line from `p1` to `p2`
-//   line_of([n=], [p1=], [p2=]) children;
+//   line_of([n=], [p1=], [p2=]) CHILDREN;
 // Usage: Spread copies every given spacing, centered along the line from `p1` to `p2`
-//   line_of([spacing], [p1=], [p2=]) children;
+//   line_of([spacing], [p1=], [p2=]) CHILDREN;
 // Usage: As a function
 //   pts = line_of([spacing], [n], [p1=]);
 //   pts = line_of([spacing], [l=], [p1=]);
@@ -157,9 +157,9 @@ function line_of(spacing, n, l, p1, p2) =
 //   Spreads out `n` copies of the children along a line on the X axis.
 //
 // Usage:
-//   xcopies(spacing, [n], [sp]) children;
+//   xcopies(spacing, [n], [sp]) CHILDREN;
-//   xcopies(l, [n], [sp]) children;
+//   xcopies(l, [n], [sp]) CHILDREN;
-//   xcopies(LIST) children;
+//   xcopies(LIST) CHILDREN;
 //
 // Arguments:
 //   spacing = Given a scalar, specifies a uniform spacing between copies. Given a list of scalars, each one gives a specific position along the line. (Default: 1.0)
@@ -210,9 +210,9 @@ module xcopies(spacing, n, l, sp)
 //   Spreads out `n` copies of the children along a line on the Y axis.
 //
 // Usage:
-//   ycopies(spacing, [n], [sp]) children;
+//   ycopies(spacing, [n], [sp]) CHILDREN;
-//   ycopies(l, [n], [sp]) children;
+//   ycopies(l, [n], [sp]) CHILDREN;
-//   ycopies(LIST) children;
+//   ycopies(LIST) CHILDREN;
 //
 // Arguments:
 //   spacing = Given a scalar, specifies a uniform spacing between copies. Given a list of scalars, each one gives a specific position along the line. (Default: 1.0)
@@ -263,9 +263,9 @@ module ycopies(spacing, n, l, sp)
 //   Spreads out `n` copies of the children along a line on the Z axis.
 //
 // Usage:
-//   zcopies(spacing, [n], [sp]) children;
+//   zcopies(spacing, [n], [sp]) CHILDREN;
-//   zcopies(l, [n], [sp]) children;
+//   zcopies(l, [n], [sp]) CHILDREN;
-//   zcopies(LIST) children;
+//   zcopies(LIST) CHILDREN;
 //
 // Arguments:
 //   spacing = Given a scalar, specifies a uniform spacing between copies. Given a list of scalars, each one gives a specific position along the line. (Default: 1.0)
@@ -333,10 +333,10 @@ module zcopies(spacing, n, l, sp)
 //   Makes a square or hexagonal grid of copies of children, with an optional masking polygon or region.  
 //
 // Usage:
-//   grid2d(spacing, size=, [stagger=], [scale=], [inside=]) children;
+//   grid2d(spacing, size=, [stagger=], [scale=], [inside=]) CHILDREN;
-//   grid2d(n=, size=, [stagger=], [scale=], [inside=]) children;
+//   grid2d(n=, size=, [stagger=], [scale=], [inside=]) CHILDREN;
-//   grid2d(spacing, [n], [stagger=], [scale=], [inside=]) children;
+//   grid2d(spacing, [n], [stagger=], [scale=], [inside=]) CHILDREN;
-//   grid2d(n=, inside=, [stagger], [scale]) children;
+//   grid2d(n=, inside=, [stagger], [scale]) CHILDREN;
 //
 // Arguments:
 //   spacing = Distance between copies in [X,Y] or scalar distance.
@@ -476,9 +476,9 @@ module grid2d(spacing, n, size, stagger=false, inside=undef, nonzero)
 //   The first (unrotated) copy will be placed at the relative starting angle `sa`.
 //
 // Usage:
-//   rot_copies(rots, [cp=], [sa=], [delta=], [subrot=]) children;
+//   rot_copies(rots, [cp=], [sa=], [delta=], [subrot=]) CHILDREN;
-//   rot_copies(rots, v, [cp=], [sa=], [delta=], [subrot=]) children;
+//   rot_copies(rots, v, [cp=], [sa=], [delta=], [subrot=]) CHILDREN;
-//   rot_copies(n=, [v=], [cp=], [sa=], [delta=], [subrot=]) children;
+//   rot_copies(n=, [v=], [cp=], [sa=], [delta=], [subrot=]) CHILDREN;
 //
 // Arguments:
 //   rots = A list of [X,Y,Z] rotation angles in degrees.  If `v` is given, this will be a list of scalar angles in degrees to rotate around `v`.
@@ -554,8 +554,8 @@ module rot_copies(rots=[], v=undef, cp=[0,0,0], n=undef, sa=0, offset=0, delta=[
 // Module: xrot_copies()
 //
 // Usage:
-//   xrot_copies(rots, [cp], [r=], [sa=], [subrot=]) children;
+//   xrot_copies(rots, [cp], [r=], [sa=], [subrot=]) CHILDREN;
-//   xrot_copies(n=, [cp=], [r=], [sa=], [subrot=]) children;
+//   xrot_copies(n=, [cp=], [r=], [sa=], [subrot=]) CHILDREN;
 //
 // Description:
 //   Given an array of angles, rotates copies of the children to each of those angles around the X axis.
@@ -613,8 +613,8 @@ module xrot_copies(rots=[], cp=[0,0,0], n=undef, sa=0, r=0, subrot=true)
 // Module: yrot_copies()
 //
 // Usage:
-//   yrot_copies(rots, [cp], [r=], [sa=], [subrot=]) children;
+//   yrot_copies(rots, [cp], [r=], [sa=], [subrot=]) CHILDREN;
-//   yrot_copies(n=, [cp=], [r=], [sa=], [subrot=]) children;
+//   yrot_copies(n=, [cp=], [r=], [sa=], [subrot=]) CHILDREN;
 //
 // Description:
 //   Given an array of angles, rotates copies of the children to each of those angles around the Y axis.
@@ -672,8 +672,8 @@ module yrot_copies(rots=[], cp=[0,0,0], n=undef, sa=0, r=0, subrot=true)
 // Module: zrot_copies()
 //
 // Usage:
-//   zrot_copies(rots, [cp], [r=], [sa=], [subrot=]) children;
+//   zrot_copies(rots, [cp], [r=], [sa=], [subrot=]) CHILDREN;
-//   zrot_copies(n=, [cp=], [r=], [sa=], [subrot=]) children;
+//   zrot_copies(n=, [cp=], [r=], [sa=], [subrot=]) CHILDREN;
 //
 // Description:
 //   Given an array of angles, rotates copies of the children to each of those angles around the Z axis.
@@ -733,8 +733,8 @@ module zrot_copies(rots=[], cp=[0,0,0], n=undef, sa=0, r=0, subrot=true)
 //   Evenly distributes n duplicate children around an ovoid arc on the XY plane.
 //
 // Usage:
-//   arc_of(n, r|d=, [sa=], [ea=], [rot=]) children;
+//   arc_of(n, r|d=, [sa=], [ea=], [rot=]) CHILDREN;
-//   arc_of(n, rx=|dx=, ry=|dy=, [sa=], [ea=], [rot=]) children;
+//   arc_of(n, rx=|dx=, ry=|dy=, [sa=], [ea=], [rot=]) CHILDREN;
 //
 // Arguments:
 //   n = number of copies to distribute around the circle. (Default: 6)
@@ -807,7 +807,7 @@ module arc_of(
 //   Spreads children semi-evenly over the surface of a sphere.
 //
 // Usage:
-//   ovoid_spread(n, r|d=, [cone_ang=], [scale=], [perp=]) children;
+//   ovoid_spread(n, r|d=, [cone_ang=], [scale=], [perp=]) CHILDREN;
 //
 // Arguments:
 //   n = How many copies to evenly spread over the surface.
@@ -873,7 +873,7 @@ module ovoid_spread(n=100, r=undef, d=undef, cone_ang=90, scale=[1,1,1], perp=tr
 //   If you specify `sp` then the copies will start at `sp`.
 //
 // Usage:
-//   path_spread(path, [n], [spacing], [sp], [rotate_children], [closed]) children;
+//   path_spread(path, [n], [spacing], [sp], [rotate_children], [closed]) CHILDREN;
 //
 // Arguments:
 //   path = path or 1-region where children are placed
@@ -1009,7 +1009,7 @@ module path_spread(path, n, spacing, sp=undef, rotate_children=true, closed)
 //   Makes a copy of the children, mirrored across the given plane.
 //
 // Usage:
-//   mirror_copy(v, [cp], [offset]) children;
+//   mirror_copy(v, [cp], [offset]) CHILDREN;
 //
 // Arguments:
 //   v = The normal vector of the plane to mirror across.
@@ -1064,7 +1064,7 @@ module mirror_copy(v=[0,0,1], offset=0, cp)
 //   Makes a copy of the children, mirrored across the X axis.
 //
 // Usage:
-//   xflip_copy([offset], [x]) children;
+//   xflip_copy([offset], [x]) CHILDREN;
 //
 // Arguments:
 //   offset = Distance to offset children right, before copying.
@@ -1098,7 +1098,7 @@ module xflip_copy(offset=0, x=0)
 //   Makes a copy of the children, mirrored across the Y axis.
 //
 // Usage:
-//   yflip_copy([offset], [y]) children;
+//   yflip_copy([offset], [y]) CHILDREN;
 //
 // Arguments:
 //   offset = Distance to offset children back, before copying.
@@ -1132,7 +1132,7 @@ module yflip_copy(offset=0, y=0)
 //   Makes a copy of the children, mirrored across the Z axis.
 //
 // Usage:
-//   zflip_copy([offset], [z]) children;
+//   zflip_copy([offset], [z]) CHILDREN;
 //
 // Arguments:
 //   offset = Distance to offset children up, before copying.
@@ -1172,8 +1172,8 @@ module zflip_copy(offset=0, z=0)
 //   where you only really care about the spacing between them.
 //
 // Usage:
-//   distribute(spacing, sizes, dir) children;
+//   distribute(spacing, sizes, dir) CHILDREN;
-//   distribute(l=, [sizes=], [dir=]) children;
+//   distribute(l=, [sizes=], [dir=]) CHILDREN;
 //
 // Arguments:
 //   spacing = Spacing to add between each child. (Default: 10.0)
@@ -1218,8 +1218,8 @@ module distribute(spacing=undef, sizes=undef, dir=RIGHT, l=undef)
 //   where you only really care about the spacing between them.
 //
 // Usage:
-//   xdistribute(spacing, [sizes]) children;
+//   xdistribute(spacing, [sizes]) CHILDREN;
-//   xdistribute(l=, [sizes=]) children;
+//   xdistribute(l=, [sizes=]) CHILDREN;
 //
 // Arguments:
 //   spacing = spacing between each child. (Default: 10.0)
@@ -1264,8 +1264,8 @@ module xdistribute(spacing=10, sizes=undef, l=undef)
 //   where you only really care about the spacing between them.
 //
 // Usage:
-//   ydistribute(spacing, [sizes]) children;
+//   ydistribute(spacing, [sizes]) CHILDREN;
-//   ydistribute(l=, [sizes=]) children;
+//   ydistribute(l=, [sizes=]) CHILDREN;
 //
 // Arguments:
 //   spacing = spacing between each child. (Default: 10.0)
@@ -1310,8 +1310,8 @@ module ydistribute(spacing=10, sizes=undef, l=undef)
 //   where you only really care about the spacing between them.
 //
 // Usage:
-//   zdistribute(spacing, [sizes]) children;
+//   zdistribute(spacing, [sizes]) CHILDREN;
-//   zdistribute(l=, [sizes=]) children;
+//   zdistribute(l=, [sizes=]) CHILDREN;
 //
 // Arguments:
 //   spacing = spacing between each child. (Default: 10.0)

drawing.scad

@@ -534,9 +534,9 @@ module stroke(
 
 // Function&Module: dashed_stroke()
 // Usage: As a Module
-//   dashed_stroke(path, dashpat, [closed=]);
+//   dashed_stroke(path, dashpat, [width=], [closed=]);
 // Usage: As a Function
-//   dashes = dashed_stroke(path, dashpat, width=, [closed=]);
+//   dashes = dashed_stroke(path, dashpat, [closed=]);
 // Topics: Paths, Drawing Tools
 // See Also: stroke(), path_cut()
 // Description:
@@ -595,17 +595,19 @@ module dashed_stroke(path, dashpat=[3,3], width=1, closed=false) {
 
 // Function&Module: arc()
 // Usage: 2D arc from 0º to `angle` degrees.
-//   arc(n, r|d=, angle);
+//   path=arc(n, r|d=, angle);
 // Usage: 2D arc from START to END degrees.
-//   arc(n, r|d=, angle=[START,END])
+//   path=arc(n, r|d=, angle=[START,END]);
 // Usage: 2D arc from `start` to `start+angle` degrees.
-//   arc(n, r|d=, start=, angle=)
+//   path=arc(n, r|d=, start=, angle=);
 // Usage: 2D circle segment by `width` and `thickness`, starting and ending on the X axis.
-//   arc(n, width=, thickness=)
+//   path=arc(n, width=, thickness=);
 // Usage: Shortest 2D or 3D arc around centerpoint `cp`, starting at P0 and ending on the vector pointing from `cp` to `P1`.
-//   arc(n, cp=, points=[P0,P1], [long=], [cw=], [ccw=])
+//   path=arc(n, cp=, points=[P0,P1], [long=], [cw=], [ccw=]);
 // Usage: 2D or 3D arc, starting at `P0`, passing through `P1` and ending at `P2`.
-//   arc(n, points=[P0,P1,P2])
+//   path=arc(n, points=[P0,P1,P2]);
+// Usage: as module
+//   arc(...) [ATTACHMENTS];
 // Topics: Paths (2D), Paths (3D), Shapes (2D), Path Generators
 // Description:
 //   If called as a function, returns a 2D or 3D path forming an arc.
@@ -742,7 +744,7 @@ module arc(n, r, angle, d, cp, points, width, thickness, start, wedge=false, anc
 
 // Function: helix()
 // Usage:
-//   helix([l|h], [turns], [angle], r|r1|r2, d|d1|d2)
+//   path = helix(l|h, [turns=], [angle=], r=|r1=|r2=, d=|d1=|d2=);
 // Description:
 //   Returns a 3D helical path on a cone, including the degerate case of flat spirals.
 //   You can specify start and end radii.  You can give the length, the helix angle, or the number of turns: two

math.scad

@@ -142,7 +142,7 @@ function sqr(x) =
 
 // Function: log2()
 // Usage:
-//   foo = log2(x);
+//   val = log2(x);
 // Description:
 //   Returns the logarithm base 2 of the value given.
 // Example:
@@ -565,12 +565,11 @@ function median(v) =
 
 // Function: deltas()
 // Usage:
-//   delts = deltas(v);
+//   delts = deltas(v,[wrap]);
 // Description:
 //   Returns a list with the deltas of adjacent entries in the given list, optionally wrapping back to the front.
 //   The list should be a consistent list of numeric components (numbers, vectors, matrix, etc).
 //   Given [a,b,c,d], returns [b-a,c-b,d-c].
-//   
 // Arguments:
 //   v = The list to get the deltas of.
 //   wrap = If true, wrap back to the start from the end.  ie: return the difference between the last and first items as the last delta.  Default: false
@@ -748,7 +747,7 @@ function rand_int(minval, maxval, n, seed=undef) =
 
 // Function: random_points()
 // Usage:
-//    points = random_points([n], [dim], [scale], [seed]);
+//    points = random_points(n, dim, [scale], [seed]);
 // See Also: random_polygon(), spherical_random_points()
 // Topics: Random, Points
 // Description:
@@ -760,7 +759,7 @@ function rand_int(minval, maxval, n, seed=undef) =
 //    dim = dimension of the points. Default: 2
 //    scale = the scale of the point coordinates. Default: 1
 //    seed = an optional seed for the random generation.
-function random_points(n, dim=2, scale=1, seed) =
+function random_points(n, dim, scale=1, seed) =
     assert( is_int(n) && n>=0, "The number of points should be a non-negative integer.")
     assert( is_int(dim) && dim>=1, "The point dimensions should be an integer greater than 1.")
     assert( is_finite(scale) || is_vector(scale,dim), "The scale should be a number or a vector with length equal to d.")
@@ -848,7 +847,7 @@ function spherical_random_points(n=1, radius=1, seed) =
 
 // Function: random_polygon()
 // Usage:
-//    points = random_polygon(n, size, [seed]);
+//    points = random_polygon([n], [size], [seed]);
 // See Also: random_points(), spherical_random_points()
 // Topics: Random, Polygon
 // Description:

partitions.scad

@@ -14,7 +14,7 @@
 // Function&Module: half_of()
 //
 // Usage: as module
-//   half_of(v, [cp], [s], [planar]) ...
+//   half_of(v, [cp], [s], [planar]) CHILDREN;
 // Usage: as function
 //   result = half_of(p,v,[cp]);
 //
@@ -40,6 +40,7 @@
 //   half_of([1,1], planar=true) circle(d=50);
 module half_of(v=UP, cp, s=100, planar=false)
 {
+    req_children($children);
     cp = is_vector(v,4)? assert(cp==undef, "Don't use cp with plane definition.") plane_normal(v) * v[3] :
         is_vector(cp)? cp :
         is_num(cp)? cp*unit(v) :
@@ -119,8 +120,8 @@ function half_of(p, v=UP, cp) =
 // Function&Module: left_half()
 //
 // Usage: as module
-//   left_half([s], [x]) ...
+//   left_half([s], [x]) CHILDREN;
-//   left_half(planar=true, [s], [x]) ...
+//   left_half(planar=true, [s], [x]) CHILDREN;
 // Usage: as function
 //   result = left_half(p, [x]);
 //
@@ -142,6 +143,7 @@ function half_of(p, v=UP, cp) =
 //   left_half(planar=true) circle(r=20);
 module left_half(s=100, x=0, planar=false)
 {
+    req_children($children);
     dir = LEFT;
     difference() {
         children();
@@ -161,10 +163,10 @@ function left_half(p,x=0) = half_of(p, LEFT, [x,0,0]);
 // Function&Module: right_half()
 //
 // Usage: as module
-//   right_half([s=], [x=]) ...
+//   right_half([s=], [x=]) CHILDREN;
-//   right_half(planar=true, [s=], [x=]) ...
+//   right_half(planar=true, [s=], [x=]) CHILDREN;
 // Usage: as function
-//   result = right_half(p=, [x=]);
+//   result = right_half(p, [x=]);
 //
 // Description:
 //   Slices an object at a vertical Y-Z cut plane, and masks away everything that is left of it.
@@ -202,8 +204,8 @@ function right_half(p,x=0) = half_of(p, RIGHT, [x,0,0]);
 // Function&Module: front_half()
 //
 // Usage:
-//   front_half([s], [y]) ...
+//   front_half([s], [y]) CHILDREN;
-//   front_half(planar=true, [s], [y]) ...
+//   front_half(planar=true, [s], [y]) CHILDREN;
 // Usage: as function
 //   result = front_half(p, [y]);
 //
@@ -224,6 +226,7 @@ function right_half(p,x=0) = half_of(p, RIGHT, [x,0,0]);
 //   front_half(planar=true) circle(r=20);
 module front_half(s=100, y=0, planar=false)
 {
+    req_children($children);
     dir = FWD;
     difference() {
         children();
@@ -243,8 +246,8 @@ function front_half(p,y=0) = half_of(p, FRONT, [0,y,0]);
 // Function&Module: back_half()
 //
 // Usage:
-//   back_half([s], [y]) ...
+//   back_half([s], [y]) CHILDREN;
-//   back_half(planar=true, [s], [y]) ...
+//   back_half(planar=true, [s], [y]) CHILDREN;
 // Usage: as function
 //   result = back_half(p, [y]);
 //
@@ -265,6 +268,7 @@ function front_half(p,y=0) = half_of(p, FRONT, [0,y,0]);
 //   back_half(planar=true) circle(r=20);
 module back_half(s=100, y=0, planar=false)
 {
+    req_children($children);
     dir = BACK;
     difference() {
         children();
@@ -284,7 +288,7 @@ function back_half(p,y=0) = half_of(p, BACK, [0,y,0]);
 // Function&Module: bottom_half()
 //
 // Usage:
-//   bottom_half([s], [z]) ...
+//   bottom_half([s], [z]) CHILDREN;
 // Usage: as function
 //   result = bottom_half(p, [z]);
 //
@@ -302,6 +306,7 @@ function back_half(p,y=0) = half_of(p, BACK, [0,y,0]);
 //   bottom_half(z=-10) sphere(r=20);
 module bottom_half(s=100, z=0)
 {
+    req_children($children);
     dir = DOWN;
     difference() {
         children();
@@ -316,8 +321,9 @@ function bottom_half(p,z=0) = half_of(p,BOTTOM,[0,0,z]);
 
 // Function&Module: top_half()
 //
-// Usage:
+// Usage: as module
-//   top_half([s], [z]) ...
+//   top_half([s], [z]) CHILDREN;
+// Usage: as function
 //   result = top_half(p, [z]);
 //
 // Description:
@@ -334,6 +340,7 @@ function bottom_half(p,z=0) = half_of(p,BOTTOM,[0,0,z]);
 //   top_half(z=5) sphere(r=20);
 module top_half(s=100, z=0)
 {
+    req_children($children);
     dir = UP;
     difference() {
         children();
@@ -392,7 +399,7 @@ function _partition_cutpath(l, h, cutsize, cutpath, gap) =
 
 // Module: partition_mask()
 // Usage:
-//   partition_mask(l, w, h, [cutsize], [cutpath], [gap], [inverse], [spin], [orient],);
+//   partition_mask(l, w, h, [cutsize], [cutpath], [gap], [inverse], [spin], [orient]) [ATTACHMENTS];
 // Description:
 //   Creates a mask that you can use to difference or intersect with an object to remove half of it, leaving behind a side designed to allow assembly of the sub-parts.
 // Arguments:
@@ -442,7 +449,7 @@ module partition_mask(l=100, w=100, h=100, cutsize=10, cutpath="jigsaw", gap=0,
 
 // Module: partition_cut_mask()
 // Usage:
-//   partition_cut_mask(l, w, h, [cutsize], [cutpath], [gap], [inverse], [spin], [orient]);
+//   partition_cut_mask(l, w, h, [cutsize], [cutpath], [gap], [inverse], [spin], [orient]) [ATTACHMENTS];
 // Description:
 //   Creates a mask that you can use to difference with an object to cut it into two sub-parts that can be assembled.
 //   The `$slop` value is important to get the proper fit and should probably be smaller than 0.2.  The examples below
@@ -485,7 +492,7 @@ module partition_cut_mask(l=100, h=100, cutsize=10, cutpath="jigsaw", gap=0, anc
 
 // Module: partition()
 // Usage:
-//   partition(size, [spread], [cutsize], [cutpath], [gap], [spin]) ...
+//   partition(size, [spread], [cutsize], [cutpath], [gap], [spin]) CHILDREN;
 // Description:
 //   Partitions an object into two parts, spread apart a small distance, with matched joining edges.
 // Arguments:
@@ -510,6 +517,7 @@ module partition_cut_mask(l=100, h=100, cutsize=10, cutpath="jigsaw", gap=0, anc
 //   partition(cutpath="jigsaw") cylinder(h=50, d=80, center=false);
 module partition(size=100, spread=10, cutsize=10, cutpath="jigsaw", gap=0, spin=0)
 {
+    req_children($children);
     size = is_vector(size)? size : [size,size,size];
     cutsize = is_vector(cutsize)? cutsize : [cutsize*2, cutsize];
     rsize = v_abs(rot(spin,p=size));

regions.scad

@@ -281,7 +281,7 @@ function force_region(poly) = is_path(poly) ? [poly] : poly;
 
 // Module: region()
 // Usage:
-//   region(r, [anchor], [spin=], [cp=], [atype=]) [attachments];
+//   region(r, [anchor], [spin=], [cp=], [atype=]) [ATTACHMENTS];
 // Description:
 //   Creates the 2D polygons described by the given region or list of polygons.  This module works on
 //   arbitrary lists of polygons that cross each other and hence do not define a valid region.  The
@@ -983,7 +983,7 @@ function _list_three(a,b,c) =
 
 // Function&Module: union()
 // Usage:
-//   union() children;
+//   union() CHILDREN;
 //   region = union(regions);
 //   region = union(REGION1,REGION2);
 //   region = union(REGION1,REGION2,REGION3);
@@ -1013,7 +1013,7 @@ function union(regions=[],b=undef,c=undef,eps=EPSILON) =
 
 // Function&Module: difference()
 // Usage:
-//   difference() children;
+//   difference() CHILDREN;
 //   region = difference(regions);
 //   region = difference(REGION1,REGION2);
 //   region = difference(REGION1,REGION2,REGION3);
@@ -1045,7 +1045,7 @@ function difference(regions=[],b=undef,c=undef,eps=EPSILON) =
 
 // Function&Module: intersection()
 // Usage:
-//   intersection() children;
+//   intersection() CHILDREN;
 //   region = intersection(regions);
 //   region = intersection(REGION1,REGION2);
 //   region = intersection(REGION1,REGION2,REGION3);
@@ -1076,7 +1076,7 @@ function intersection(regions=[],b=undef,c=undef,eps=EPSILON) =
 
 // Function&Module: exclusive_or()
 // Usage:
-//   exclusive_or() children;
+//   exclusive_or() CHILDREN;
 //   region = exclusive_or(regions);
 //   region = exclusive_or(REGION1,REGION2);
 //   region = exclusive_or(REGION1,REGION2,REGION3);

rounding.scad

@@ -1241,7 +1241,7 @@ module offset_stroke(path, width=1, rounded=true, start, end, check_valid=true,
 
 // Function&Module: offset_sweep()
 // Usage: most common module arguments.  See Arguments list below for more.
-//    offset_sweep(path, [height|length|h|l|], [bottom], [top], [offset=], [convexity=],...) {attachments};
+//    offset_sweep(path, [height|length|h|l|], [bottom], [top], [offset=], [convexity=],...) [ATTACHMENTS];
 // Usage: most common function arguments.  See Arguments list below for more.
 //    vnf = offset_sweep(path, [height|h|l|length], [bottom], [top], [offset=], ...);
 // Description:
@@ -1707,7 +1707,7 @@ function os_mask(mask, out=false, extra,check_valid, quality, offset) =
 
 // Module: convex_offset_extrude()
 // Usage: Basic usage.  See below for full options
-//   convex_offset_extrude(height, [bottom], [top], ...) 2D-children;
+//   convex_offset_extrude(height, [bottom], [top], ...) 2D-CHILDREN;
 // Description:
 //   Extrudes 2d children with layers formed from the convex hull of the offset of each child according to a sequence of offset values.
 //   Like `offset_sweep` this module can use built-in offset profiles to provide treatments such as roundovers or chamfers but unlike `offset_sweep()` it
@@ -1939,7 +1939,7 @@ function _rp_compute_patches(top, bot, rtop, rsides, ktop, ksides, concave) =
 
 // Function&Module: rounded_prism()
 // Usage: as a module
-//   rounded_prism(bottom, [top], [height=|h=|length=|l=], [joint_top=], [joint_bot=], [joint_sides=], [k=], [k_top=], [k_bot=], [k_sides=], [splinesteps=], [debug=], [convexity=],...) {attachments};
+//   rounded_prism(bottom, [top], [height=|h=|length=|l=], [joint_top=], [joint_bot=], [joint_sides=], [k=], [k_top=], [k_bot=], [k_sides=], [splinesteps=], [debug=], [convexity=],...) [ATTACHMENTS];
 // Usage: as a function
 //   vnf = rounded_prism(bottom, [top], [height=|h=|length=|l=], [joint_top=], [joint_bot=], [joint_sides=], [k=], [k_top=], [k_bot=], [k_sides=], [splinesteps=], [debug=]);
 // Description:
@@ -2476,8 +2476,8 @@ Access to the derivative smoothing parameter?
 
 // Function&Module: join_prism()
 // Usage: The two main forms with most common options
-//   join_prism(polygon, base, length=|height=|l=|h=, fillet=, [base_T=], [scale=], [prism_end_T=], [short=], ...) {attachments};
+//   join_prism(polygon, base, length=|height=|l=|h=, fillet=, [base_T=], [scale=], [prism_end_T=], [short=], ...) [ATTACHMENTS];
-//   join_prism(polygon, base, aux=, fillet=, [base_T=], [aux_T=], [scale=], [prism_end_T=], [short=], ...) {attachments};
+//   join_prism(polygon, base, aux=, fillet=, [base_T=], [aux_T=], [scale=], [prism_end_T=], [short=], ...) [ATTACHMENTS];
 // Usage: As function
 //   vnf = join_prism( ... );
 // Description:

shapes2d.scad

@@ -25,7 +25,7 @@ use <builtins.scad>
 // Usage: As a Module
 //   square(size, [center], ...);
 // Usage: With Attachments
-//   square(size, [center], ...) { attachables }
+//   square(size, [center], ...) [ATTACHMENTS];
 // Usage: As a Function
 //   path = square(size, [center], ...);
 // See Also: rect()
@@ -72,9 +72,7 @@ module square(size=1, center, anchor, spin) {
 
 // Function&Module: rect()
 // Usage: As Module
-//   rect(size, [rounding], [chamfer], ...);
+//   rect(size, [rounding], [chamfer], ...) [ATTACHMENTS];
-// Usage: With Attachments
-//   rect(size, ...) { attachables }
 // Usage: As Function
 //   path = rect(size, [rounding], [chamfer], ...);
 // Topics: Shapes (2D), Paths (2D), Path Generators, Attachable
@@ -205,9 +203,7 @@ function rect(size=1, rounding=0, chamfer=0, atype="box", anchor=CENTER, spin=0)
 // Function&Module: circle()
 // Topics: Shapes (2D), Path Generators (2D)
 // Usage: As a Module
-//   circle(r|d=, ...);
+//   circle(r|d=, ...) [ATTACHMENTS];
-// Usage: With Attachments
-//   circle(r|d=, ...) { attachables }
 // Usage: As a Function
 //   path = circle(r|d=, ...);
 // See Also: ellipse(), circle_2tangents(), circle_3points()
@@ -245,9 +241,7 @@ module circle(r, d, anchor=CENTER, spin=0) {
 
 // Function&Module: ellipse()
 // Usage: As a Module
-//   ellipse(r|d=, [realign=], [circum=], ...);
+//   ellipse(r|d=, [realign=], [circum=], ...) [ATTACHMENTS];
-// Usage: With Attachments
-//   ellipse(r|d=, [realign=], [circum=], ...) { attachables }
 // Usage: As a Function
 //   path = ellipse(r|d=, [realign=], [circum=], ...);
 // Topics: Shapes (2D), Paths (2D), Path Generators, Attachable
@@ -427,9 +421,9 @@ function ellipse(r, d, realign=false, circum=false, uniform=false, anchor=CENTER
 
 // Function&Module: regular_ngon()
 // Usage:
-//   regular_ngon(n, r/d=/or=/od=, [realign=]);
+//   regular_ngon(n, r|d=|or=|od=, [realign=]) [ATTACHMENTS];
-//   regular_ngon(n, ir=/id=, [realign=]);
+//   regular_ngon(n, ir=|id=, [realign=]) [ATTACHMENTS];
-//   regular_ngon(n, side=, [realign=]);
+//   regular_ngon(n, side=, [realign=]) [ATTACHMENTS];
 // Topics: Shapes (2D), Paths (2D), Path Generators, Attachable
 // See Also: circle(), pentagon(), hexagon(), octagon(), ellipse(), star()
 // Description:
@@ -563,9 +557,11 @@ module regular_ngon(n=6, r, d, or, od, ir, id, side, rounding=0, realign=false,
 
 // Function&Module: pentagon()
 // Usage:
-//   pentagon(or|od=, [realign=]);
+//   pentagon(or|od=, [realign=], [align_tip=|align_side=]) [ATTACHMENTS];
-//   pentagon(ir=|id=, [realign=]);
+//   pentagon(ir=|id=, [realign=], [align_tip=|align_side=]) [ATTACHMENTS];
-//   pentagon(side=, [realign=]);
+//   pentagon(side=, [realign=], [align_tip=|align_side=]) [ATTACHMENTS];
+// Usage: as function
+//   path = pentagon(...);
 // Topics: Shapes (2D), Paths (2D), Path Generators, Attachable
 // See Also: circle(), regular_ngon(), hexagon(), octagon(), ellipse(), star()
 // Description:
@@ -619,17 +615,12 @@ module pentagon(r, d, or, od, ir, id, side, rounding=0, realign=false, align_tip
 
 // Function&Module: hexagon()
 // Usage: As Module
-//   hexagon(r/or, [realign=], <align_tip=|align_side=>, [rounding=], ...);
+//   hexagon(r/or, [realign=], <align_tip=|align_side=>, [rounding=], ...) [ATTACHMENTS];
-//   hexagon(d=/od=, ...);
+//   hexagon(d=/od=, ...) [ATTACHMENTS];
-//   hexagon(ir=/id=, ...);
+//   hexagon(ir=/id=, ...) [ATTACHMENTS];
-//   hexagon(side=, ...);
+//   hexagon(side=, ...) [ATTACHMENTS];
-// Usage: With Attachments
-//   hexagon(r/or, ...) { attachments }
 // Usage: As Function
-//   path = hexagon(r/or, ...);
+//   path = hexagon(...);
-//   path = hexagon(d=/od=, ...);
-//   path = hexagon(ir=/id=, ...);
-//   path = hexagon(side=, ...);
 // Topics: Shapes (2D), Paths (2D), Path Generators, Attachable
 // See Also: circle(), regular_ngon(), pentagon(), octagon(), ellipse(), star()
 // Description:
@@ -683,17 +674,12 @@ module hexagon(r, d, or, od, ir, id, side, rounding=0, realign=false, align_tip,
 
 // Function&Module: octagon()
 // Usage: As Module
-//   octagon(r/or, [realign=], <align_tip=|align_side=>, [rounding=], ...);
+//   octagon(r/or, [realign=], [align_tip=|align_side=], [rounding=], ...) [ATTACHMENTS];
-//   octagon(d=/od=, ...);
+//   octagon(d=/od=, ...) [ATTACHMENTS];
-//   octagon(ir=/id=, ...);
+//   octagon(ir=/id=, ...) [ATTACHMENTS];
-//   octagon(side=, ...);
+//   octagon(side=, ...) [ATTACHMENTS];
-// Usage: With Attachments
-//   octagon(r/or, ...) { attachments }
 // Usage: As Function
-//   path = octagon(r/or, ...);
+//   path = octagon(...);
-//   path = octagon(d=/od=, ...);
-//   path = octagon(ir=/id=, ...);
-//   path = octagon(side=, ...);
 // Topics: Shapes (2D), Paths (2D), Path Generators, Attachable
 // See Also: circle(), regular_ngon(), pentagon(), hexagon(), ellipse(), star()
 // Description:
@@ -746,9 +732,7 @@ module octagon(r, d, or, od, ir, id, side, rounding=0, realign=false, align_tip,
 
 // Function&Module: right_triangle()
 // Usage: As Module
-//   right_triangle(size, [center], ...);
+//   right_triangle(size, [center], ...) [ATTACHMENTS];
-// Usage: With Attachments
-//   right_triangle(size, [center], ...) { attachments }
 // Usage: As Function
 //   path = right_triangle(size, [center], ...);
 // Description:
@@ -772,6 +756,7 @@ function right_triangle(size=[1,1], center, anchor, spin=0) =
         anchor = get_anchor(anchor, center, [-1,-1], [-1,-1])
     )
     assert(is_vector(size,2))
+    assert(min(size)>0, "Must give positive size")
     let(
         path = [ [size.x/2,-size.y/2], [-size.x/2,-size.y/2], [-size.x/2,size.y/2] ]
     ) reorient(anchor,spin, two_d=true, size=[size.x,size.y], size2=0, shift=-size.x/2, p=path);
@@ -790,17 +775,12 @@ module right_triangle(size=[1,1], center, anchor, spin=0) {
 
 // Function&Module: trapezoid()
 // Usage: As Module
-//   trapezoid(h, w1, w2, [shift=], [rounding=], [chamfer=], ...);
+//   trapezoid(h, w1, w2, [shift=], [rounding=], [chamfer=], ...) [ATTACHMENTS];
-//   trapezoid(h, w1, angle=, ...);
+//   trapezoid(h, w1, angle=, ...) [ATTACHMENTS];
-//   trapezoid(h, w2, angle=, ...);
+//   trapezoid(h, w2, angle=, ...) [ATTACHMENTS];
-//   trapezoid(w1, w2, angle=, ...);
+//   trapezoid(w1, w2, angle=, ...) [ATTACHMENTS];
-// Usage: With Attachments
-//   trapezoid(h, w1, w2, ...) { attachments }
 // Usage: As Function
-//   path = trapezoid(h, w1, w2, ...);
+//   path = trapezoid(...);
-//   path = trapezoid(h, w1, angle=, ...);
-//   path = trapezoid(h, w2=, angle=, ...);
-//   path = trapezoid(w1=, w2=, angle=, ...);
 // Topics: Shapes (2D), Paths (2D), Path Generators, Attachable
 // See Also: rect(), square()
 // Description:
@@ -947,10 +927,8 @@ module trapezoid(h, w1, w2, angle, shift=0, chamfer=0, rounding=0, flip=false, a
 
 // Function&Module: star()
 // Usage: As Module
-//   star(n, r/or, ir, [realign=], [align_tip=], [align_pit=], ...);
+//   star(n, r/or, ir, [realign=], [align_tip=], [align_pit=], ...) [ATTACHMENTS];
-//   star(n, r/or, step=, ...);
+//   star(n, r/or, step=, ...) [ATTACHMENTS];
-// Usage: With Attachments
-//   star(n, r/or, ir, ...) { attachments }
 // Usage: As Function
 //   path = star(n, r/or, ir, [realign=], [align_tip=], [align_pit=], ...);
 //   path = star(n, r/or, step=, ...);
@@ -1132,11 +1110,11 @@ function _path_add_jitter(path, dist=1/512, closed=true) =
 //   linear_extrude(height=h, twist=72, slices=h/quadsize)
 //      jittered_poly(spath);
 module jittered_poly(path, dist=1/512) {
+    no_children($children);
     polygon(_path_add_jitter(path, dist, closed=true));
 }
 
 
-
 // Section: Curved 2D Shapes
 
 
@@ -1146,9 +1124,7 @@ module jittered_poly(path, dist=1/512) {
 //   Makes a 2D teardrop shape. Useful for extruding into 3D printable holes.  Uses "intersect" style anchoring.  
 //
 // Usage: As Module
-//   teardrop2d(r/d=, [ang], [cap_h]);
+//   teardrop2d(r/d=, [ang], [cap_h]) [ATTACHMENTS];
-// Usage: With Attachments
-//   teardrop2d(r/d=, [ang], [cap_h], ...) { attachments }
 // Usage: As Function
 //   path = teardrop2d(r/d=, [ang], [cap_h]);
 //
@@ -1200,9 +1176,9 @@ function teardrop2d(r, ang=45, cap_h, d, anchor=CENTER, spin=0) =
 
 // Function&Module: egg()
 // Usage: As Module
-//   egg(length, r1, r2, R);
+//   egg(length, r1|d1=, r2|d2=, R|D=) [ATTACHMENTS];
 // Usage: As Function
-//   path = egg(length, r1|d2, r2|d2, R|D);
+//   path = egg(length, r1|d1=, r2|d2=, R|D=);
 // Topics: Shapes (2D), Paths (2D), Path Generators, Attachable
 // See Also: circle(), ellipse(), glued_circles()
 // Description:
@@ -1287,11 +1263,9 @@ module egg(length,r1,r2,R,d1,d2,D,anchor=CENTER, spin=0)
 
 // Function&Module: glued_circles()
 // Usage: As Module
-//   glued_circles(r/d=, [spread=], [tangent=], ...);
+//   glued_circles(r/d=, [spread], [tangent], ...) [ATTACHMENTS];
-// Usage: With Attachments
-//   glued_circles(r/d=, [spread=], [tangent=], ...) { attachments }
 // Usage: As Function
-//   path = glued_circles(r/d=, [spread=], [tangent=], ...);
+//   path = glued_circles(r/d=, [spread], [tangent], ...);
 // Topics: Shapes (2D), Paths (2D), Path Generators, Attachable
 // See Also: circle(), ellipse(), egg()
 // Description:
@@ -1357,11 +1331,9 @@ function _superformula(theta,m1,m2,n1,n2=1,n3=1,a=1,b=1) =
 
 // Function&Module: supershape()
 // Usage: As Module
-//   supershape(step, [m1=], [m2=], [n1=], [n2=], [n3=], [a=], [b=], <r=/d=>);
+//   supershape(step, [m1=], [m2=], [n1=], [n2=], [n3=], [a=], [b=], [r=/d=]) [ATTACHMENTS];
-// Usage: With Attachments
-//   supershape(step, [m1=], [m2=], [n1=], [n2=], [n3=], [a=], [b=], <r=/d=>) { attachments }
 // Usage: As Function
-//   path = supershape(step, [m1=], [m2=], [n1=], [n2=], [n3=], [a=], [b=], <r=/d=>);
+//   path = supershape(step, [m1=], [m2=], [n1=], [n2=], [n3=], [a=], [b=], [r=/d=]);
 // Topics: Shapes (2D), Paths (2D), Path Generators, Attachable
 // See Also: circle(), ellipse()
 // Description:
@@ -1438,9 +1410,9 @@ module supershape(step=0.5,m1=4,m2=undef,n1,n2=undef,n3=undef,a=1,b=undef, r=und
 
 // Function&Module: reuleaux_polygon()
 // Usage: As Module
-//   reuleaux_polygon(n, r|d, ...);
+//   reuleaux_polygon(n, r|d=, ...) [ATTACHMENTS];
 // Usage: As Function
-//   path = reuleaux_polygon(n, r|d, ...);
+//   path = reuleaux_polygon(n, r|d=, ...);
 // Topics: Shapes (2D), Paths (2D), Path Generators, Attachable
 // See Also: regular_ngon(), pentagon(), hexagon(), octagon()
 // Description:
@@ -1510,7 +1482,7 @@ function reuleaux_polygon(n=3, r, d, anchor=CENTER, spin=0) =
 //   text(text, [size], [font], ...);
 // Description:
 //   Creates a 3D text block that can be attached to other attachable objects.
-//   NOTE: This cannot have children attached to it.
+//   NOTE: You cannot attach children to this.
 // Arguments:
 //   text = The text string to instantiate as an object.
 //   size = The font size used to create the text block.  Default: 10
@@ -1598,10 +1570,10 @@ module text(text, size=10, font="Helvetica", halign, valign, spacing=1.0, direct
 
 // Module: round2d()
 // Usage:
-//   round2d(r) ...
+//   round2d(r) [ATTACHMENTS];
-//   round2d(or) ...
+//   round2d(or=) [ATTACHMENTS];
-//   round2d(ir) ...
+//   round2d(ir=) [ATTACHMENTS];
-//   round2d(or, ir) ...
+//   round2d(or=, ir=) [ATTACHMENTS];
 // Description:
 //   Rounds arbitrary 2D objects.  Giving `r` rounds all concave and convex corners.  Giving just `ir`
 //   rounds just concave corners.  Giving just `or` rounds convex corners.  Giving both `ir` and `or`
@@ -1609,6 +1581,7 @@ module text(text, size=10, font="Helvetica", halign, valign, spacing=1.0, direct
 //   any parts narrower than twice the `or` radius.  Such parts will disappear.
 // Arguments:
 //   r = Radius to round all concave and convex corners to.
+//   ---
 //   or = Radius to round only outside (convex) corners to.  Use instead of `r`.
 //   ir = Radius to round only inside (concave) corners to.  Use instead of `r`.
 // Examples(2D):
@@ -1626,7 +1599,7 @@ module round2d(r, or, ir)
 
 // Module: shell2d()
 // Usage:
-//   shell2d(thickness, [or], [ir], [fill], [round])
+//   shell2d(thickness, [or], [ir])
 // Description:
 //   Creates a hollow shell from 2D children, with optional rounding.
 // Arguments:

shapes3d.scad

@@ -22,7 +22,7 @@ use <builtins.scad>
 // Usage: As Module
 //   cube(size, [center], ...);
 // Usage: With Attachments
-//   cube(size, [center], ...) { attachments }
+//   cube(size, [center], ...) [ATTACHMENTS];
 // Usage: As Function
 //   vnf = cube(size, [center], ...);
 // See Also: cuboid(), prismoid()
@@ -96,7 +96,7 @@ function cube(size=1, center, anchor, spin=0, orient=UP) =
 // Usage: Rounded Cubes
 //   cuboid(size, [rounding=], [teardrop=], [edges=], [except=], [trimcorners=], ...);
 // Usage: Attaching children
-//   cuboid(size, [anchor=], ...) [attachments];
+//   cuboid(...) ATTACHMENTS;
 //
 // Description:
 //   Creates a cube or cuboid object, with optional chamfering or rounding of edges and corners.
@@ -490,15 +490,13 @@ function cuboid(
 // Function&Module: prismoid()
 //
 // Usage: Typical Prismoids
-//   prismoid(size1, size2, h|l, [shift], ...);
+//   prismoid(size1, size2, h|l, [shift], ...) [ATTACHMENTS];
-// Usage: Attaching Children
-//   prismoid(size1, size2, h|l, [shift], ...) [attachments];
 // Usage: Chamfered Prismoids
-//   prismoid(size1, size2, h|l, [chamfer=], ...);
+//   prismoid(size1, size2, h|l, [chamfer=], ...) [ATTACHMENTS];
-//   prismoid(size1, size2, h|l, [chamfer1=], [chamfer2=], ...);
+//   prismoid(size1, size2, h|l, [chamfer1=], [chamfer2=], ...) [ATTACHMENTS];
 // Usage: Rounded Prismoids
-//   prismoid(size1, size2, h|l, [rounding=], ...);
+//   prismoid(size1, size2, h|l, [rounding=], ...) [ATTACHMENTS];
-//   prismoid(size1, size2, h|l, [rounding1=], [rounding2=], ...);
+//   prismoid(size1, size2, h|l, [rounding1=], [rounding2=], ...) [ATTACHMENTS];
 // Usage: As Function
 //   vnf = prismoid(size1, size2, h|l, [shift], [rounding], [chamfer]);
 //   vnf = prismoid(size1, size2, h|l, [shift], [rounding1], [rounding2], [chamfer1], [chamfer2]);
@@ -692,9 +690,7 @@ function prismoid(
 
 // Function&Module: octahedron()
 // Usage: As Module
-//   octahedron(size, ...);
+//   octahedron(size, ...) [ATTACHMENTS];
-// Usage: With Attachments
-//   octahedron(size, ...) { attachments }
 // Usage: As Function
 //   vnf = octahedron(size, ...);
 // Description:
@@ -750,7 +746,7 @@ function octahedron(size=1, anchor=CENTER, spin=0, orient=UP) =
 //   rect_tube(h, size, isize, irounding1=, irounding2= ...);
 //   rect_tube(h, size, isize, rounding=, irounding=, ...);
 // Usage: Attaching Children
-//   rect_tube(h, size, isize, ...) [attachments];
+//   rect_tube(...) ATTACHMENTS;
 //
 // Description:
 //   Creates a rectangular or prismoid tube with optional roundovers and/or chamfers.
@@ -924,9 +920,7 @@ function rect_tube(
 // Function&Module: wedge()
 //
 // Usage: As Module
-//   wedge(size, [center], ...);
+//   wedge(size, [center], ...) [ATTACHMENTS];
-// Usage: With Attachments
-//   wedge(size, [center], ...) { attachments }
 // Usage: As Function
 //   vnf = wedge(size, [center], ...);
 //
@@ -985,10 +979,8 @@ function wedge(size=[1,1,1], center, anchor, spin=0, orient=UP) =
 // Function&Module: cylinder()
 // Topics: Shapes (3D), Attachable, VNF Generators
 // Usage: As Module
-//   cylinder(h, r=/d=, [center=], ...);
+//   cylinder(h, r=/d=, [center=], ...) [ATTACHMENTS];
-//   cylinder(h, r1/d1=, r2/d2=, [center=], ...);
+//   cylinder(h, r1/d1=, r2/d2=, [center=], ...) [ATTACHMENTS];
-// Usage: With Attachments
-//   cylinder(h, r=/d=, [center=]) {attachments}
 // Usage: As Function
 //   vnf = cylinder(h, r=/d=, [center=], ...);
 //   vnf = cylinder(h, r1/d1=, r2/d2=, [center=], ...);
@@ -1073,10 +1065,10 @@ function cylinder(h, r1, r2, center, l, r, d, d1, d2, anchor, spin=0, orient=UP)
 //   the cylinder's length.
 //
 // Usage: Normal Cylinders
-//   cyl(l|h, r, [center], [circum=], [realign=]);
+//   cyl(l|h, r, [center], [circum=], [realign=]) [ATTACHMENTS];
-//   cyl(l|h, d=, ...);
+//   cyl(l|h, d=, ...) [ATTACHMENTS];
-//   cyl(l|h, r1=, r2=, ...);
+//   cyl(l|h, r1=, r2=, ...) [ATTACHMENTS];
-//   cyl(l|h, d1=, d2=, ...);
+//   cyl(l|h, d1=, d2=, ...) [ATTACHMENTS];
 //
 // Usage: Chamferred Cylinders
 //   cyl(l|h, r|d, chamfer=, [chamfang=], [from_end=], ...);
@@ -1273,11 +1265,8 @@ module cyl(
 //   Creates a cylinder oriented along the X axis.
 //
 // Usage: Typical
-//   xcyl(l|h, r, [anchor=]);
+//   xcyl(l|h, r|d=, [anchor=], ...) [ATTACHMENTS];
-//   xcyl(l|h, d=, [anchor=]);
+//   xcyl(l|h, r1=|d1=, r2=|d2=, [anchor=], ...) [ATTACHMENTS];
-//   xcyl(l|h, r1=|d1=, r2=|d2=, [anchor=]);
-// Usage: Attaching Children
-//   xcyl(l|h, r, [anchor=]) [attachments];
 //
 // Arguments:
 //   l / h = Length of cylinder along oriented axis. Default: 1
@@ -1346,11 +1335,8 @@ module xcyl(
 //   Creates a cylinder oriented along the Y axis.
 //
 // Usage: Typical
-//   ycyl(l|h, r, [anchor=]);
+//   ycyl(l|h, r|d=, [anchor=], ...) [ATTACHMENTS];
-//   ycyl(l|h, d=, [anchor=]);
+//   ycyl(l|h, r1=|d1=, r2=|d2=, [anchor=], ...) [ATTACHMENTS];
-//   ycyl(l|h, r1=|d1=, r2=|d2=, [anchor=]);
-// Usage: Attaching Children
-//   ycyl(l|h, r, [anchor=]) [attachments];
 //
 // Arguments:
 //   l / h = Length of cylinder along oriented axis. (Default: `1.0`)
@@ -1420,11 +1406,8 @@ module ycyl(
 //   Creates a cylinder oriented along the Z axis.
 //
 // Usage: Typical
-//   zcyl(l|h, r, [anchor=]);
+//   zcyl(l|h, r|d=, [anchor=],...) [ATTACHMENTS];
-//   zcyl(l|h, d=, [anchor=]);
+//   zcyl(l|h, r1=|d1=, r2=|d2=, [anchor=],...);
-//   zcyl(l|h, r1=|d1=, r2=|d2=, [anchor=]);
-// Usage: Attaching Children
-//   zcyl(l|h, r, [anchor=]) [attachments];
 //
 // Arguments:
 //   l / h = Length of cylinder along oriented axis. (Default: 1.0)
@@ -1502,7 +1485,7 @@ module zcyl(
 //   tube(h|l, or1|od1, or2|od2, wall, ...);
 //   tube(h|l, ir1|id1, ir2|id2, or1|od1, or2|od2, [realign]);
 // Usage: Attaching Children
-//   tube(h|l, or, ir, [center]) [attachments];
+//   tube(...) ATTACHMENTS;
 //
 // Arguments:
 //   h / l = height of tube. Default: 1
@@ -1589,7 +1572,7 @@ module tube(
 //   vnf = pie_slice(l|h, d=, ang=, ...);
 //   vnf = pie_slice(l|h, r1=|d1=, r2=|d2=, ang=, ...);
 // Usage: Attaching Children
-//   pie_slice(l|h, r, ang, ...) [attachments];
+//   pie_slice(l|h, r, ang, ...) ATTACHMENTS;
 //
 // Arguments:
 //   h / l = height of pie slice.
@@ -1674,9 +1657,7 @@ function pie_slice(
 // Function&Module: sphere()
 // Topics: Shapes (3D), Attachable, VNF Generators
 // Usage: As Module
-//   sphere(r|d=, [circum=], [style=], ...);
+//   sphere(r|d=, [circum=], [style=], ...) [ATTACHMENTS];
-// Usage: With Attachments
-//   sphere(r|d=, ...) { attachments }
 // Usage: As Function
 //   vnf = sphere(r|d=, [circum=], [style=], ...);
 // See Also: spheroid()
@@ -1740,9 +1721,7 @@ function sphere(r, d, circum=false, style="orig", anchor=CENTER, spin=0, orient=
 
 // Function&Module: spheroid()
 // Usage: Typical
-//   spheroid(r|d, [circum], [style]);
+//   spheroid(r|d, [circum], [style]) [ATTACHMENTS];
-// Usage: Attaching Children
-//   spheroid(r|d, [circum], [style]) [attachments];
 // Usage: As Function
 //   vnf = spheroid(r|d, [circum], [style]);
 // Description:
@@ -2069,14 +2048,12 @@ function spheroid(r, style="aligned", d, circum=false, anchor=CENTER, spin=0, or
 // Function&Module: torus()
 //
 // Usage: As Module
-//   torus(r_maj|d_maj, r_min|d_min, [center], ...);
+//   torus(r_maj|d_maj, r_min|d_min, [center], ...) [ATTACHMENTS];
-//   torus(or|od, ir|id, ...);
+//   torus(or|od, ir|id, ...) [ATTACHMENTS];
-//   torus(r_maj|d_maj, or|od, ...);
+//   torus(r_maj|d_maj, or|od, ...) [ATTACHMENTS];
-//   torus(r_maj|d_maj, ir|id, ...);
+//   torus(r_maj|d_maj, ir|id, ...) [ATTACHMENTS];
-//   torus(r_min|d_min, or|od, ...);
+//   torus(r_min|d_min, or|od, ...) [ATTACHMENTS];
-//   torus(r_min|d_min, ir|id, ...);
+//   torus(r_min|d_min, ir|id, ...) [ATTACHMENTS];
-// Usage: Attaching Children
-//   torus(or|od, ir|id, ...) [attachments];
 // Usage: As Function
 //   vnf = torus(r_maj|d_maj, r_min|d_min, [center], ...);
 //   vnf = torus(or|od, ir|id, ...);
@@ -2213,13 +2190,11 @@ function torus(
 //   Makes a teardrop shape in the XZ plane. Useful for 3D printable holes.
 //
 // Usage: Typical
-//   teardrop(h|l, r, [ang], [cap_h], ...);
+//   teardrop(h|l, r, [ang], [cap_h], ...) [ATTACHMENTS];
-//   teardrop(h|l, d=, [ang=], [cap_h=], ...);
+//   teardrop(h|l, d=, [ang=], [cap_h=], ...) [ATTACHMENTS];
 // Usage: Psuedo-Conical
-//   teardrop(h|l, r1=, r2=, [ang=], [cap_h1=], [cap_h2=], ...);
+//   teardrop(h|l, r1=, r2=, [ang=], [cap_h1=], [cap_h2=], ...)  [ATTACHMENTS];
-//   teardrop(h|l, d1=, d2=, [ang=], [cap_h1=], [cap_h2=], ...);
+//   teardrop(h|l, d1=, d2=, [ang=], [cap_h1=], [cap_h2=], ...)  [ATTACHMENTS];
-// Usage: Attaching Children
-//   teardrop(h|l, r, ...) [attachments];
 // Usage: As Function
 //   vnf = teardrop(h|l=, r|d=, [ang=], [cap_h=], ...);
 //   vnf = teardrop(h|l=, r1=|d1=, r2=|d2=, [ang=], [cap_h=], ...);
@@ -2348,9 +2323,7 @@ function teardrop(h, r, ang=45, cap_h, r1, r2, d, d1, d2, cap_h1, cap_h2, l, anc
 //   Creates a sphere with a conical hat, to make a 3D teardrop.
 //
 // Usage: As Module
-//   onion(r|d=, [ang=], [cap_h=], ...);
+//   onion(r|d=, [ang=], [cap_h=], ...) [ATTACHMENTS];
-// Usage: Attaching Children
-//   onion(r, ...) [attachments];
 // Usage: As Function
 //   vnf = onion(r|d=, [ang=], [cap_h=], ...);
 //
@@ -2530,7 +2503,7 @@ function _cut_interp(pathcut, path, data) =
 
 // Module: path_text()
 // Usage:
-//   path_text(path, text, [size], [thickness], [font], [lettersize], [offset], [reverse], [normal], [top], [textmetrics])
+//   path_text(path, text, [size], [thickness], [font], [lettersize], [offset], [reverse], [normal], [top], [textmetrics], [kern])
 // Description:
 //   Place the text letter by letter onto the specified path using textmetrics (if available and requested)
 //   or user specified letter spacing.  The path can be 2D or 3D.  In 2D the text appears along the path with letters upright
@@ -2638,6 +2611,7 @@ function _cut_interp(pathcut, path, data) =
 
 module path_text(path, text, font, size, thickness, lettersize, offset=0, reverse=false, normal, top, center=false, textmetrics=false, kern=0)
 {
+  no_children($children);
   dummy2=assert(is_path(path,[2,3]),"Must supply a 2d or 3d path")
          assert(num_defined([normal,top])<=1, "Cannot define both \"normal\" and \"top\"");
   dim = len(path[0]);
@@ -2716,10 +2690,8 @@ module path_text(path, text, font, size, thickness, lettersize, offset=0, revers
 //   Center this part along the concave edge to be chamfered and union it in.
 //
 // Usage: Typical
-//   interior_fillet(l, r, [ang], [overlap], ...);
+//   interior_fillet(l, r, [ang], [overlap], ...) [ATTACHMENTS];
-//   interior_fillet(l, d=, [ang=], [overlap=], ...);
+//   interior_fillet(l, d=, [ang=], [overlap=], ...) [ATTACHMENTS];
-// Usage: Attaching Children
-//   interior_fillet(l, r, [ang], [overlap], ...) [attachments];
 //
 // Arguments:
 //   l = Length of edge to fillet.
@@ -2777,9 +2749,7 @@ module interior_fillet(l=1.0, r, ang=90, overlap=0.01, d, anchor=FRONT+LEFT, spi
 
 // Function&Module: heightfield()
 // Usage: As Module
-//   heightfield(data, [size], [bottom], [maxz], [xrange], [yrange], [style], [convexity], ...);
+//   heightfield(data, [size], [bottom], [maxz], [xrange], [yrange], [style], [convexity], ...) [ATTACHMENTS];
-// Usage: Attaching Children
-//   heightfield(data, [size], ...) [attachments];
 // Usage: As Function
 //   vnf = heightfield(data, [size], [bottom], [maxz], [xrange], [yrange], [style], ...);
 // Description:
@@ -2904,7 +2874,7 @@ function heightfield(data, size=[100,100], bottom=-20, maxz=100, xrange=[-1:0.04
 
 // Module: ruler()
 // Usage:
-//   ruler(length, width, [thickness=], [depth=], [labels=], [pipscale=], [maxscale=], [colors=], [alpha=], [unit=], [inch=]);
+//   ruler(length, width, [thickness=], [depth=], [labels=], [pipscale=], [maxscale=], [colors=], [alpha=], [unit=], [inch=]) [ATTACHMENTS];
 // Description:
 //   Creates a ruler for checking dimensions of the model
 // Arguments:

skin.scad

@@ -19,7 +19,7 @@
 
 // Function&Module: skin()
 // Usage: As module:
-//   skin(profiles, slices, [z=], [refine=], [method=], [sampling=], [caps=], [closed=], [style=], [convexity=], [anchor=],[cp=],[spin=],[orient=],[atype=]) {attachments};
+//   skin(profiles, slices, [z=], [refine=], [method=], [sampling=], [caps=], [closed=], [style=], [convexity=], [anchor=],[cp=],[spin=],[orient=],[atype=]) [ATTACHMENTS];
 // Usage: As function:
 //   vnf = skin(profiles, slices, [z=], [refine=], [method=], [sampling=], [caps=], [closed=], [style=], [anchor=],[cp=],[spin=],[orient=],[atype=]);
 // Description:
@@ -504,7 +504,7 @@ function skin(profiles, slices, refine=1, method="direct", sampling, caps, close
 
 // Function&Module: linear_sweep()
 // Usage:
-//   linear_sweep(region, [height], [center=], [slices=], [twist=], [scale=], [style=], [convexity=]) {attachments};
+//   linear_sweep(region, [height], [center=], [slices=], [twist=], [scale=], [style=], [convexity=]) [ATTACHMENTS];
 // Description:
 //   If called as a module, creates a polyhedron that is the linear extrusion of the given 2D region or polygon.
 //   If called as a function, returns a VNF that can be used to generate a polyhedron of the linear extrusion
@@ -623,7 +623,7 @@ function linear_sweep(region, height=1, center, twist=0, scale=1, slices,
 
 // Function&Module: spiral_sweep()
 // Usage:
-//   spiral_sweep(poly, h, r, turns, [higbee=], [center=], [r1=], [r2=], [d=], [d1=], [d2=], [higbee1=], [higbee2=], [internal=], [anchor=], [spin=], [orient=]){attachments};
+//   spiral_sweep(poly, h, r, turns, [higbee=], [center=], [r1=], [r2=], [d=], [d1=], [d2=], [higbee1=], [higbee2=], [internal=], [anchor=], [spin=], [orient=])[ATTACHMENTS];
 //   vnf = spiral_sweep(poly, h, r, turns, ...);
 // Description:
 //   Takes a closed 2D polygon path, centered on the XY plane, and sweeps/extrudes it along a 3D spiral path
@@ -731,9 +731,9 @@ module spiral_sweep(poly, h, r, turns=1, higbee, center, r1, r2, d, d1, d2, higb
 
 // Function&Module: path_sweep()
 // Usage: As module
-//   path_sweep(shape, path, [method], [normal=], [closed=], [twist=], [twist_by_length=], [symmetry=], [last_normal=], [tangent=], [uniform=], [relaxed=], [caps=], [style=], [convexity=], [anchor=], [cp=], [spin=], [orient=], [atype=]) {attachments};
+//   path_sweep(shape, path, [method], [normal=], [closed=], [twist=], [twist_by_length=], [symmetry=], [last_normal=], [tangent=], [uniform=], [relaxed=], [caps=], [style=], [convexity=], [anchor=], [cp=], [spin=], [orient=], [atype=]) [ATTACHMENTS];
 // Usage: As function
-//   vnf = path_sweep(shape, path, [method], [normal=], [closed=], [twist=], [twist_by_length=], [symmetry=], [last_normal=], [tangent=], [uniform=], [relaxed=], [caps=], [style=], [transforms=], [anchor=], [cp=], [spin=], [orient=], [atype=]) {attachments};
+//   vnf = path_sweep(shape, path, [method], [normal=], [closed=], [twist=], [twist_by_length=], [symmetry=], [last_normal=], [tangent=], [uniform=], [relaxed=], [caps=], [style=], [transforms=], [anchor=], [cp=], [spin=], [orient=], [atype=]);
 // Description:
 //   Takes as input `shape`, a 2D polygon path (list of points), and `path`, a 2d or 3d path (also a list of points)
 //   and constructs a polyhedron by sweeping the shape along the path. When run as a module returns the polyhedron geometry.
@@ -1264,7 +1264,7 @@ function path_sweep(shape, path, method="incremental", normal, closed=false, twi
 
 // Function&Module: path_sweep2d()
 // Usage: as module
-//   path_sweep2d(shape, path, [closed], [caps], [quality], [style], [convexity=], [anchor=], [spin=], [orient=], [atype=], [cp=]) {attachments};
+//   path_sweep2d(shape, path, [closed], [caps], [quality], [style], [convexity=], [anchor=], [spin=], [orient=], [atype=], [cp=]) [ATTACHMENTS];
 // Usage: as function
 //   vnf = path_sweep2d(shape, path, [closed], [caps], [quality], [style], [anchor=], [spin=], [orient=], [atype=], [cp=]);
 // Description:
@@ -1388,7 +1388,7 @@ function _ofs_face_edge(face,firstlen,second=false) =
 
 // Function&Module: sweep()
 // Usage: As Module
-//   sweep(shape, transforms, [closed], [caps], [style], [convexity=], [anchor=], [spin=], [orient=], [atype=]) [attachments];
+//   sweep(shape, transforms, [closed], [caps], [style], [convexity=], [anchor=], [spin=], [orient=], [atype=]) [ATTACHMENTS];
 // Usage: As Function
 //   vnf = sweep(shape, transforms, [closed], [caps], [style], [anchor=], [spin=], [orient=], [atype=]);
 // Description:

threading.scad

@@ -22,6 +22,7 @@
 //   d = Outer diameter of threaded rod, or a triplet of [d_min, d_pitch, d_major]. 
 //   l = length of threaded rod.
 //   pitch = Length between threads.
+//   ---
 //   left_handed = if true, create left-handed threads.  Default = false
 //   bevel = if true, bevel the thread ends.  Default: false
 //   bevel1 = if true bevel the bottom end.

transforms.scad

@@ -75,7 +75,7 @@ _NO_ARG = [true,[123232345],false];
 // Aliases: translate()
 //
 // Usage: As Module
-//   move(v) children;
+//   move(v) CHILDREN;
 // Usage: As a function to translate points, VNF, or Bezier patch
 //   pts = move(v, p);
 //   pts = move(STRING, p);
@@ -161,7 +161,7 @@ function translate(v=[0,0,0], p=_NO_ARG) = move(v=v, p=p);
 // Function&Module: left()
 //
 // Usage: As Module
-//   left(x) children;
+//   left(x) CHILDREN;
 // Usage: Translate Points
 //   pts = left(x, p);
 // Usage: Get Translation Matrix
@@ -204,7 +204,7 @@ function left(x=0, p=_NO_ARG) =
 // Aliases: xmove()
 //
 // Usage: As Module
-//   right(x) children;
+//   right(x) CHILDREN;
 // Usage: Translate Points
 //   pts = right(x, p);
 // Usage: Get Translation Matrix
@@ -257,7 +257,7 @@ function xmove(x=0, p=_NO_ARG) =
 // Function&Module: fwd()
 //
 // Usage: As Module
-//   fwd(y) children;
+//   fwd(y) CHILDREN;
 // Usage: Translate Points
 //   pts = fwd(y, p);
 // Usage: Get Translation Matrix
@@ -300,7 +300,7 @@ function fwd(y=0, p=_NO_ARG) =
 // Aliases: ymove()
 //
 // Usage: As Module
-//   back(y) children;
+//   back(y) CHILDREN;
 // Usage: Translate Points
 //   pts = back(y, p);
 // Usage: Get Translation Matrix
@@ -353,7 +353,7 @@ function ymove(y=0,p=_NO_ARG) =
 // Function&Module: down()
 //
 // Usage: As Module
-//   down(z) children;
+//   down(z) CHILDREN;
 // Usage: Translate Points
 //   pts = down(z, p);
 // Usage: Get Translation Matrix
@@ -394,7 +394,7 @@ function down(z=0, p=_NO_ARG) =
 // Aliases: zmove()
 //
 // Usage: As Module
-//   up(z) children;
+//   up(z) CHILDREN;
 // Usage: Translate Points
 //   pts = up(z, p);
 // Usage: Get Translation Matrix
@@ -452,10 +452,10 @@ function zmove(z=0, p=_NO_ARG) =
 // Function&Module: rot()
 //
 // Usage: As a Module
-//   rot(a, [cp=], [reverse=]) children;
+//   rot(a, [cp=], [reverse=]) CHILDREN;
-//   rot([X,Y,Z], [cp=], [reverse=]) children;
+//   rot([X,Y,Z], [cp=], [reverse=]) CHILDREN;
-//   rot(a, v, [cp=], [reverse=]) children;
+//   rot(a, v, [cp=], [reverse=]) CHILDREN;
-//   rot(from=, to=, [a=], [reverse=]) children;
+//   rot(from=, to=, [a=], [reverse=]) CHILDREN;
 // Usage: As a Function to transform data in `p`
 //   pts = rot(a, p=, [cp=], [reverse=]);
 //   pts = rot([X,Y,Z], p=, [cp=], [reverse=]);
@@ -556,7 +556,7 @@ function rot(a=0, v, cp, from, to, reverse=false, p=_NO_ARG, _m) =
 // Function&Module: xrot()
 //
 // Usage: As Module
-//   xrot(a, [cp=]) children;
+//   xrot(a, [cp=]) CHILDREN;
 // Usage: As a function to rotate points
 //   rotated = xrot(a, p, [cp=]);
 // Usage: As a function to return rotation matrix
@@ -602,7 +602,7 @@ function xrot(a=0, p=_NO_ARG, cp) = rot([a,0,0], cp=cp, p=p);
 // Function&Module: yrot()
 //
 // Usage: As Module
-//   yrot(a, [cp=]) children;
+//   yrot(a, [cp=]) CHILDREN;
 // Usage: Rotate Points
 //   rotated = yrot(a, p, [cp=]);
 // Usage: Get Rotation Matrix
@@ -648,7 +648,7 @@ function yrot(a=0, p=_NO_ARG, cp) = rot([0,a,0], cp=cp, p=p);
 // Function&Module: zrot()
 //
 // Usage: As Module
-//   zrot(a, [cp=]) children;
+//   zrot(a, [cp=]) CHILDREN;
 // Usage: As Function to rotate points
 //   rotated = zrot(a, p, [cp=]);
 // Usage: As Function to return rotation matrix
@@ -699,8 +699,8 @@ function zrot(a=0, p=_NO_ARG, cp) = rot(a, cp=cp, p=p);
 
 // Function&Module: scale()
 // Usage: As Module
-//   scale(SCALAR) children;
+//   scale(SCALAR) CHILDREN;
-//   scale([X,Y,Z]) children;
+//   scale([X,Y,Z]) CHILDREN;
 // Usage: Scale Points
 //   pts = scale(v, p, [cp=]);
 // Usage: Get Scaling Matrix
@@ -750,7 +750,7 @@ function scale(v=1, p=_NO_ARG, cp=[0,0,0]) =
 //
 //
 // Usage: As Module
-//   xscale(x, [cp=]) children;
+//   xscale(x, [cp=]) CHILDREN;
 // Usage: Scale Points
 //   scaled = xscale(x, p, [cp=]);
 // Usage: Get Affine Matrix
@@ -804,7 +804,7 @@ function xscale(x=1, p=_NO_ARG, cp=0) =
 // Function&Module: yscale()
 //
 // Usage: As Module
-//   yscale(y, [cp=]) children;
+//   yscale(y, [cp=]) CHILDREN;
 // Usage: Scale Points
 //   scaled = yscale(y, p, [cp=]);
 // Usage: Get Affine Matrix
@@ -858,7 +858,7 @@ function yscale(y=1, p=_NO_ARG, cp=0) =
 // Function&Module: zscale()
 //
 // Usage: As Module
-//   zscale(z, [cp=]) children;
+//   zscale(z, [cp=]) CHILDREN;
 // Usage: Scale Points
 //   scaled = zscale(z, p, [cp=]);
 // Usage: Get Affine Matrix
@@ -915,7 +915,7 @@ function zscale(z=1, p=_NO_ARG, cp=0) =
 
 // Function&Module: mirror()
 // Usage: As Module
-//   mirror(v) children;
+//   mirror(v) CHILDREN;
 // Usage: As Function
 //   pt = mirror(v, p);
 // Usage: Get Reflection/Mirror Matrix
@@ -985,7 +985,7 @@ function mirror(v, p=_NO_ARG) =
 // Function&Module: xflip()
 //
 // Usage: As Module
-//   xflip([x=]) children;
+//   xflip([x=]) CHILDREN;
 // Usage: As Function
 //   pt = xflip(p, [x]);
 // Usage: Get Affine Matrix
@@ -1039,7 +1039,7 @@ function xflip(p=_NO_ARG, x=0) =
 // Function&Module: yflip()
 //
 // Usage: As Module
-//   yflip([y=]) children;
+//   yflip([y=]) CHILDREN;
 // Usage: As Function
 //   pt = yflip(p, [y]);
 // Usage: Get Affine Matrix
@@ -1093,7 +1093,7 @@ function yflip(p=_NO_ARG, y=0) =
 // Function&Module: zflip()
 //
 // Usage: As Module
-//   zflip([z=]) children;
+//   zflip([z=]) CHILDREN;
 // Usage: As Function
 //   pt = zflip(p, [z]);
 // Usage: Get Affine Matrix
@@ -1146,7 +1146,7 @@ function zflip(p=_NO_ARG, z=0) =
 
 // Function&Module: frame_map()
 // Usage: As module
-//   frame_map(v1, v2, v3, [reverse=]) children;
+//   frame_map(v1, v2, v3, [reverse=]) CHILDREN;
 // Usage: As function to remap points
 //   transformed = frame_map(v1, v2, v3, p=points, [reverse=]);
 // Usage: As function to return a transformation matrix:
@@ -1234,7 +1234,7 @@ module frame_map(x,y,z,p,reverse=false)
 
 // Function&Module: skew()
 // Usage: As Module
-//   skew([sxy=], [sxz=], [syx=], [syz=], [szx=], [szy=]) children;
+//   skew([sxy=], [sxz=], [syx=], [syz=], [szx=], [szy=]) CHILDREN;
 // Usage: As Function
 //   pts = skew(p, [sxy=], [sxz=], [syx=], [syz=], [szx=], [szy=]);
 // Usage: Get Affine Matrix

vnf.scad

@@ -831,8 +831,8 @@ function _slice_3dpolygons(polys, dir, cuts) =
 
 // Module: vnf_polyhedron()
 // Usage:
-//   vnf_polyhedron(vnf);
+//   vnf_polyhedron(vnf) [ATTACHMENTS];
-//   vnf_polyhedron([VNF, VNF, VNF, ...]);
+//   vnf_polyhedron([VNF, VNF, VNF, ...]) [ATTACHMENTS];
 // Description:
 //   Given a VNF structure, or a list of VNF structures, creates a polyhedron from them.
 // Arguments: