Merge pull request #1144 from RAMilewski/master

Synopses - transforms.scad, utility.scad

comparisons.scad

@@ -23,7 +23,7 @@
 // Arguments:
 //   a = First value.
 //   b = Second value.
-//   eps = The maximum allowed difference between `a` and `b` that will return true.
+//   eps = The maximum allowed difference between `a` and `b` that will return true. Defaults to 1e-9.
 // Example:
 //   test1 = approx(-0.3333333333,-1/3);  // Returns: true
 //   test2 = approx(0.3333333333,1/3);    // Returns: true

transforms.scad

@@ -83,17 +83,16 @@ _NO_ARG = [true,[123232345],false];
 //   mat = move(v);
 //
 // Synopsis: Translates children in an arbitrary direction.
+// SynTags: Geom, Path, VNF, Mat
 // Topics: Affine, Matrices, Transforms, Translation
 // See Also: left(), right(), fwd(), back(), down(), up(), spherical_to_xyz(), altaz_to_xyz(), cylindrical_to_xyz(), polar_to_xy()
 //
 // Description:
 //   Translates position by the given amount.
 //   * Called as a module, moves/translates all children.
-//   * Called as a function with a point in the `p` argument, returns the translated point.
-//   * Called as a function with a list of points in the `p` argument, returns the translated list of points.
+//   * Called as a function with the `p` argument, returns the translated point or list of points.
 //   * Called as a function with a [bezier patch](beziers.scad) in the `p` argument, returns the translated patch.
 //   * Called as a function with a [VNF structure](vnf.scad) in the `p` argument, returns the translated VNF.
-//   * Called as a function with the `p` argument, returns the translated point or list of points.
 //   * Called as a function with the `p` argument set to a VNF or a polygon and `v` set to "centroid", "mean" or "box", translates the argument to the centroid, mean, or bounding box center respectively.
 //   * Called as a function without a `p` argument, returns a 4x4 translation matrix for operating on 3D data.  
 //
@@ -105,7 +104,7 @@ _NO_ARG = [true,[123232345],false];
 //   #sphere(d=10);
 //   move([0,20,30]) sphere(d=10);
 //
-// Example: You can move a 3D object with a 2D vector.  The Z component is treated at zero.  
+// Example: You can move a 3D object with a 2D vector.  The Z component is treated as zero.  
 //   #sphere(d=10);
 //   move([-10,-5]) sphere(d=10);
 //
@@ -169,12 +168,13 @@ function translate(v=[0,0,0], p=_NO_ARG) = move(v=v, p=p);
 //   mat = left(x);
 //
 // Synopsis: Translates children leftwards (X-).
+// SynTags: Geom, Path, VNF, Mat
 // Topics: Affine, Matrices, Transforms, Translation
 // See Also: move(), right(), fwd(), back(), down(), up()
 //
 // Description:
 //   If called as a module, moves/translates all children left (in the X- direction) by the given amount.
-//   If called as a function with the `p` argument, returns the translated point or list of points.
+//   If called as a function with the `p` argument, returns the translated VNF, point or list of points.
 //   If called as a function without the `p` argument, returns an affine3d translation matrix.
 //
 // Arguments:
@@ -213,12 +213,13 @@ function left(x=0, p=_NO_ARG) =
 //   mat = right(x);
 //
 // Synopsis: Translates children rightwards (X+).
+// SynTags: Geom, Path, VNF, Mat
 // Topics: Affine, Matrices, Transforms, Translation
 // See Also: move(), left(), fwd(), back(), down(), up()
 //
 // Description:
 //   If called as a module, moves/translates all children right (in the X+ direction) by the given amount.
-//   If called as a function with the `p` argument, returns the translated point or list of points.
+//   If called as a function with the `p` argument, returns the translated VNF point or list of points.
 //   If called as a function without the `p` argument, returns an affine3d translation matrix.
 //
 // Arguments:
@@ -267,12 +268,13 @@ function xmove(x=0, p=_NO_ARG) =
 //   mat = fwd(y);
 //
 // Synopsis: Translates children forwards (Y-).
+// SynTags: Geom, Path, VNF, Mat
 // Topics: Affine, Matrices, Transforms, Translation
 // See Also: move(), left(), right(), back(), down(), up()
 //
 // Description:
 //   If called as a module, moves/translates all children forward (in the Y- direction) by the given amount.
-//   If called as a function with the `p` argument, returns the translated point or list of points.
+//   If called as a function with the `p` argument, returns the translated VNF, point or list of points.
 //   If called as a function without the `p` argument, returns an affine3d translation matrix.
 //
 // Arguments:
@@ -311,12 +313,13 @@ function fwd(y=0, p=_NO_ARG) =
 //   mat = back(y);
 //
 // Synopsis: Translates children backwards (Y+).
+// SynTags: Geom, Path, VNF, Mat
 // Topics: Affine, Matrices, Transforms, Translation
 // See Also: move(), left(), right(), fwd(), down(), up()
 //
 // Description:
 //   If called as a module, moves/translates all children back (in the Y+ direction) by the given amount.
-//   If called as a function with the `p` argument, returns the translated point or list of points.
+//   If called as a function with the `p` argument, returns the translated VNF, point or list of points.
 //   If called as a function without the `p` argument, returns an affine3d translation matrix.
 //
 // Arguments:
@@ -365,12 +368,13 @@ function ymove(y=0,p=_NO_ARG) =
 //   mat = down(z);
 //
 // Synopsis: Translates children downwards (Z-).
+// SynTags: Geom, Path, VNF, Mat
 // Topics: Affine, Matrices, Transforms, Translation
 // See Also: move(), left(), right(), fwd(), back(), up()
 //
 // Description:
 //   If called as a module, moves/translates all children down (in the Z- direction) by the given amount.
-//   If called as a function with the `p` argument, returns the translated point or list of points.
+//   If called as a function with the `p` argument, returns the translated VNF, point or list of points.
 //   If called as a function without the `p` argument, returns an affine3d translation matrix.
 //
 // Arguments:
@@ -407,12 +411,13 @@ function down(z=0, p=_NO_ARG) =
 //   mat = up(z);
 //
 // Synopsis: Translates children upwards (Z+).
+// SynTags: Geom, Path, VNF, Mat
 // Topics: Affine, Matrices, Transforms, Translation
 // See Also: move(), left(), right(), fwd(), back(), down()
 //
 // Description:
 //   If called as a module, moves/translates all children up (in the Z+ direction) by the given amount.
-//   If called as a function with the `p` argument, returns the translated point or list of points.
+//   If called as a function with the `p` argument, returns the translated VNF, point or list of points.
 //   If called as a function without the `p` argument, returns an affine3d translation matrix.
 //
 // Arguments:
@@ -475,6 +480,7 @@ function zmove(z=0, p=_NO_ARG) =
 //   M = rot(from=, to=, [a=], [reverse=]);
 //
 // Synopsis: Rotates children in various ways.
+// SynTags: Geom, Path, VNF, Mat
 // Topics: Affine, Matrices, Transforms, Rotation
 // See Also: xrot(), yrot(), zrot()
 //
@@ -571,6 +577,7 @@ function rot(a=0, v, cp, from, to, reverse=false, p=_NO_ARG, _m) =
 //   mat = xrot(a, [cp=]);
 //
 // Synopsis: Rotates children around the X axis using the right-hand rule.
+// SynTags: Geom, Path, VNF, Mat
 // Topics: Affine, Matrices, Transforms, Rotation
 // See Also: rot(), yrot(), zrot()
 //
@@ -618,6 +625,7 @@ function xrot(a=0, p=_NO_ARG, cp) = rot([a,0,0], cp=cp, p=p);
 //   mat = yrot(a, [cp=]);
 //
 // Synopsis: Rotates children around the Y axis using the right-hand rule.
+// SynTags: Geom, Path, VNF, Mat
 // Topics: Affine, Matrices, Transforms, Rotation
 // See Also: rot(), xrot(), zrot()
 //
@@ -666,6 +674,7 @@ function yrot(a=0, p=_NO_ARG, cp) = rot([0,a,0], cp=cp, p=p);
 //
 // Synopsis: Rotates children around the Z axis using the right-hand rule.
 // Topics: Affine, Matrices, Transforms, Rotation
+// SynTags: Geom, Path, VNF, Mat
 // See Also: rot(), xrot(), yrot()
 //
 // Description:
@@ -718,6 +727,7 @@ function zrot(a=0, p=_NO_ARG, cp) = rot(a, cp=cp, p=p);
 //   mat = scale(v, [cp=]);
 // Synopsis: Scales children arbitrarily.
 // Topics: Affine, Matrices, Transforms, Scaling
+// SynTags: Geom, Path, VNF, Mat
 // See Also: xscale(), yscale(), zscale()
 // Description:
 //   Scales by the [X,Y,Z] scaling factors given in `v`.  If `v` is given as a scalar number, all axes are scaled uniformly by that amount.
@@ -768,6 +778,7 @@ function scale(v=1, p=_NO_ARG, cp=[0,0,0]) =
 //   mat = xscale(x, [cp=]);
 //
 // Synopsis: Scales children along the X axis.
+// SynTags: Geom, Path, VNF, Mat
 // Topics: Affine, Matrices, Transforms, Scaling
 // See Also: scale(), yscale(), zscale()
 //
@@ -823,6 +834,7 @@ function xscale(x=1, p=_NO_ARG, cp=0) =
 //   mat = yscale(y, [cp=]);
 //
 // Synopsis: Scales children along the Y axis.
+// SynTags: Geom, Path, VNF, Mat
 // Topics: Affine, Matrices, Transforms, Scaling
 // See Also: scale(), xscale(), zscale()
 //
@@ -878,6 +890,7 @@ function yscale(y=1, p=_NO_ARG, cp=0) =
 //   mat = zscale(z, [cp=]);
 //
 // Synopsis: Scales children along the Z axis.
+// SynTags: Geom, Path, VNF, Mat
 // Topics: Affine, Matrices, Transforms, Scaling
 // See Also: scale(), xscale(), yscale()
 //
@@ -935,6 +948,7 @@ function zscale(z=1, p=_NO_ARG, cp=0) =
 // Usage: Get Reflection/Mirror Matrix
 //   mat = mirror(v);
 // Synopsis: Reflects children across an arbitrary plane.
+// SynTags: Geom, Path, VNF, Mat
 // Topics: Affine, Matrices, Transforms, Reflection, Mirroring
 // See Also: xflip(), yflip(), zflip()
 // Description:
@@ -1007,6 +1021,7 @@ function mirror(v, p=_NO_ARG) =
 //   mat = xflip([x=]);
 //
 // Synopsis: Reflects children across the YZ plane.
+// SynTags: Geom, Path, VNF, Mat
 // Topics: Affine, Matrices, Transforms, Reflection, Mirroring
 // See Also: mirror(), yflip(), zflip()
 //
@@ -1062,6 +1077,7 @@ function xflip(p=_NO_ARG, x=0) =
 //   mat = yflip([y=]);
 //
 // Synopsis: Reflects children across the XZ plane.
+// SynTags: Geom, Path, VNF, Mat
 // Topics: Affine, Matrices, Transforms, Reflection, Mirroring
 // See Also: mirror(), xflip(), zflip()
 //
@@ -1117,6 +1133,7 @@ function yflip(p=_NO_ARG, y=0) =
 //   mat = zflip([z=]);
 //
 // Synopsis: Reflects children across the XY plane.
+// SynTags: Geom, Path, VNF, Mat
 // Topics: Affine, Matrices, Transforms, Reflection, Mirroring
 // See Also: mirror(), xflip(), yflip()
 //
@@ -1173,6 +1190,7 @@ function zflip(p=_NO_ARG, z=0) =
 //   map = frame_map(x=VECTOR1, z=VECTOR2, [reverse=]);
 //   map = frame_map(y=VECTOR1, z=VECTOR2, [reverse=]);
 // Synopsis: Rotates and possibly skews children from one frame of reference to another.
+// SynTags: Geom, Path, VNF, Mat
 // Topics: Affine, Matrices, Transforms, Rotation
 // See Also: rot(), xrot(), yrot(), zrot()
 // Description:
@@ -1260,6 +1278,7 @@ module frame_map(x,y,z,p,reverse=false)
 //   mat = skew([sxy=]|[axy=], [sxz=]|[axz=], [syx=]|[ayx=], [syz=]|[ayz=], [szx=]|[azx=], [szy=]|[azy=]);
 // Topics: Affine, Matrices, Transforms, Skewing
 // Synopsis: Skews children along various axes.
+// SynTags: Geom, Path, VNF, Mat
 //
 // Description:
 //   Skews geometry by the given skew factors.
@@ -1384,6 +1403,7 @@ function is_2d_transform(t) =    // z-parameters are zero, except we allow t[2][
 //   pts = apply(transform, points);
 // Topics: Affine, Matrices, Transforms
 // Synopsis: Applies a transformation matrix to a point, list of points, array of points, or VNF.
+// SynTags: Path, VNF, Mat
 // Description:
 //   Applies the specified transformation matrix `transform` to a point, point list, bezier patch or VNF.
 //   When `points` contains 2D or 3D points the transform matrix may be a 4x4 affine matrix or a 3x4 

utility.scad

@@ -15,10 +15,11 @@
 
 
 // Function: typeof()
-// Usage:
-//   typ = typeof(x);
+// Synopsis: Returns a string representing the type of the value.
 // Topics: Type Checking
 // See Also: is_type()
+// Usage:
+//   typ = typeof(x);
 // Description:
 //   Returns a string representing the type of the value.  One of "undef", "boolean", "number", "nan", "string", "list", "range", "function" or "invalid".
 //   Some malformed "ranges", like '[0:NAN:INF]' and '[0:"a":INF]', may be classified as "undef" or "invalid".
@@ -46,10 +47,11 @@ function typeof(x) =
 
 
 // Function: is_type()
-// Usage:
-//   bool = is_type(x, types);
+// Synopsis: Returns true if the type of 'x' is one of those in the list `types`.
 // Topics: Type Checking
 // See Also: typeof()
+// Usage:
+//   bool = is_type(x, types);
 // Description:
 //   Returns true if the type of the value `x` is one of those given as strings in the list `types`. 
 //   Valid types are "undef", "boolean", "number", "nan", "string", "list", "range", or "function".
@@ -88,10 +90,11 @@ function is_def(x) = !is_undef(x);
 
 
 // Function: is_str()
+// Synopsis: Returns true if the argument is a string.
+// Topics: Type Checking
+// See Also: typeof(), is_type(), is_int(), is_def(), is_int()
 // Usage:
 //   bool = is_str(x);
-// Topics: Type Checking
-// See Also: typeof(), is_type(), is_int(), is_def()
 // Description:
 //   Returns true if `x` is a string.  A shortcut for `is_string()`.
 // Arguments:
@@ -105,12 +108,13 @@ function is_str(x) = is_string(x);
 
 
 // Function: is_int()
+// Synopsis: Returns true if the argument is an integer.
 // Alias: is_integer()
+// Topics: Type Checking
+// See Also: typeof(), is_type(), is_str(), is_def()
 // Usage:
 //   bool = is_int(n);
 //   bool = is_integer(n);
-// Topics: Type Checking
-// See Also: typeof(), is_type(), is_str(), is_def()
 // Description:
 //   Returns true if the given value is an integer (it is a number and it rounds to itself).  
 // Arguments:
@@ -125,6 +129,9 @@ function is_integer(n) = is_finite(n) && n == round(n);
 
 
 // Function: all_integer()
+// Synopsis: Returns true if all of the numbers in the argument are integers.
+// Topics: Type Checking
+// See also: is_int(), typeof(), is_type()
 // Usage:
 //   bool = all_integer(x);
 // Description:
@@ -149,10 +156,11 @@ function all_integer(x) =
 
 
 // Function: is_nan()
+// Synopsis: Return true if the argument is "not a number".
+// Topics: Type Checking
+// See Also: typeof(), is_type(), is_str(), is_def(), is_int(), is_finite()
 // Usage:
 //   bool = is_nan(x);
-// Topics: Type Checking
-// See Also: typeof(), is_type(), is_str(), is_def(), is_int()
 // Description:
 //   Returns true if a given value `x` is nan, a floating point value representing "not a number".
 // Arguments:
@@ -167,10 +175,11 @@ function is_nan(x) = (x!=x);
 
 
 // Function: is_finite()
-// Usage:
-//   bool = is_finite(x);
+// Synopsis: Returns true if the argument is a finite number.
 // Topics: Type Checking
 // See Also: typeof(), is_type(), is_str(), is_def(), is_int(), is_nan()
+// Usage:
+//   bool = is_finite(x);
 // Description:
 //   Returns true if a given value `x` is a finite number.
 // Arguments:
@@ -187,6 +196,7 @@ function is_finite(x) = is_num(x) && !is_nan(0*x);
 
 
 // Function: is_range()
+// Synopsis: Returns true if the argument is a range.
 // Usage:
 //   bool = is_range(x);
 // Topics: Type Checking
@@ -206,10 +216,11 @@ function is_range(x) = !is_list(x) && is_finite(x[0]) && is_finite(x[1]) && is_f
 
 
 // Function: valid_range()
-// Usage:
-//   bool = valid_range(x);
+// Synopsis: Returns true if the argument is a valid range.
 // Topics: Type Checking
 // See Also: typeof(), is_type(), is_str(), is_def(), is_int(), is_range()
+// Usage:
+//   bool = valid_range(x);
 // Description:
 //   Returns true if its argument is a valid range (deprecated ranges excluded).
 // Arguments:
@@ -230,6 +241,9 @@ function valid_range(x) =
 
 
 // Function: is_func()
+// Synopsis: Returns true if the argument is a function literal.
+// Topics: Type Checking, Function Literals
+// See also: is_type(), typeof()
 // Usage:
 //   bool = is_func(x);
 // Description:
@@ -243,10 +257,11 @@ function is_func(x) = version_num()>20210000 && is_function(x);
 
 
 // Function: is_consistent()
+// Synopsis: Returns true if the argument is a list with consistent structure and finite numerical data.
+// Topics: Type Checking, Testing
+// See Also: typeof(), is_type(), is_str(), is_def(), is_int(), is_range(), is_homogeneous()
 // Usage:
 //   bool = is_consistent(list, [pattern]);
-// Topics: Type Checking
-// See Also: typeof(), is_type(), is_str(), is_def(), is_int(), is_range(), is_homogeneous()
 // Description:
 //   Tests whether input is a list of entries which all have the same list structure
 //   and are filled with finite numerical data.  You can optionally specify a required 
@@ -284,10 +299,11 @@ function _list_pattern(list) =
 
 
 // Function: same_shape()
+// Synopsis: Returns true if the argument lists are numeric and of the same shape.
+// Topics: Type Checking, Testing
+// See Also: is_homogeneous(), is_consistent()
 // Usage:
 //   bool = same_shape(a,b);
-// Topics: Type Checking
-// See Also: is_homogeneous(), is_consistent()
 // Description:
 //   Tests whether the inputs `a` and `b` are both numeric and are the same shaped list.
 // Example:
@@ -297,10 +313,11 @@ function same_shape(a,b) = is_def(b) && _list_pattern(a) == b*0;
 
 
 // Function: is_bool_list()
+// Synopsis: Returns true if the argument list contains only booleans.
+// Topics: Boolean Testing
+// See Also: is_homogeneous(), is_consistent()
 // Usage:
 //   check = is_bool_list(list,[length])
-// Topics: Type Checking
-// See Also: is_homogeneous(), is_consistent()
 // Description:
 //   Tests whether input is a list containing only booleans, and optionally checks its length.
 // Arguments:
@@ -313,6 +330,9 @@ function is_bool_list(list, length) =
 // Section: Boolean list testing
 
 // Function: any()
+// Synopsis: Returns true if any item in the argument list is true.
+// Topics: Type Checking
+// See Also: all(), num_true()
 // Usage:
 //   bool = any(l);
 //   bool = any(l, func);   // Requires OpenSCAD 2021.01 or later.
@@ -348,6 +368,9 @@ function _any_bool(l, i=0, out=false) =
 
 
 // Function: all()
+// Synopsis: Returns true if all items in the argument list are true.
+// Topics: Type Checking
+// See Also: any(), num_true()
 // Usage:
 //   bool = all(l);
 //   bool = all(l, func);   // Requires OpenSCAD 2021.01 or later.
@@ -384,6 +407,9 @@ function _all_bool(l, i=0, out=true) =
 
 
 // Function: num_true()
+// Synopsis: Returns the number of true entries in the arguemnt list.
+// Topics: Boolean Testing
+// See Also: any(), all()
 // Usage:
 //   seq = num_true(l);
 //   seq = num_true(l, func);  // Requires OpenSCAD 2021.01 or later.
@@ -418,10 +444,11 @@ function num_true(l, func) =
 
 
 // Function: default()
-// Usage:
-//   val = default(val, dflt);
+// Synopsis Returns a default value if the argument is 'undef', else returns the argument.
 // Topics: Undef Handling
 // See Also: first_defined(), one_defined(), num_defined()
+// Usage:
+//   val = default(val, dflt);
 // Description:
 //   Returns the value given as `v` if it is not `undef`.
 //   Otherwise, returns the value of `dflt`.
@@ -432,10 +459,11 @@ function default(v,dflt=undef) = is_undef(v)? dflt : v;
 
 
 // Function: first_defined()
-// Usage:
-//   val = first_defined(v, [recursive]);
+// Synopsis: Returns the first value in the argument list that is not 'undef'.
 // Topics: Undef Handling
 // See Also: default(), one_defined(), num_defined(), any_defined(), all_defined()
+// Usage:
+//   val = first_defined(v, [recursive]);
 // Description:
 //   Returns the first item in the list that is not `undef`.
 //   If all items are `undef`, or list is empty, returns `undef`.
@@ -455,10 +483,11 @@ function first_defined(v,recursive=false,_i=0) =
     
 
 // Function: one_defined()
-// Usage:
-//   val = one_defined(vals, names, [dflt])
+// Synopsis: Returns the defined value in the argument list if only a single value is defined.
 // Topics: Undef Handling
 // See Also: default(), first_defined(), num_defined(), any_defined(), all_defined()
+// Usage:
+//   val = one_defined(vals, names, [dflt])
 // Description:
 //   Examines the input list `vals` and returns the entry which is not `undef`.
 //   If more than one entry is not `undef` then an error is asserted, specifying
@@ -495,10 +524,11 @@ function one_defined(vals, names, dflt=_UNDEF) =
 
 
 // Function: num_defined()
-// Usage:
-//   cnt = num_defined(v);
+// Synopsis: Returns the number of defined values in the the argument list.
 // Topics: Undef Handling
 // See Also: default(), first_defined(), one_defined(), any_defined(), all_defined()
+// Usage:
+//   cnt = num_defined(v);
 // Description:
 //   Counts how many items in list `v` are not `undef`.
 // Example:
@@ -508,10 +538,11 @@ function num_defined(v) =
 
 
 // Function: any_defined()
-// Usage:
-//   bool = any_defined(v, [recursive]);
+// Synopsis: Returns true if any item in the argument list is not `undef`.
 // Topics: Undef Handling
 // See Also: default(), first_defined(), one_defined(), num_defined(), all_defined()
+// Usage:
+//   bool = any_defined(v, [recursive]);
 // Description:
 //   Returns true if any item in the given array is not `undef`.
 // Arguments:
@@ -529,6 +560,9 @@ function any_defined(v,recursive=false) =
 
 
 // Function: all_defined()
+// Synopsis: Returns true if all items in the given array are defined.
+// Topics: Undef Handling
+// See Also: default(), first_defined(), one_defined(), num_defined(), all_defined()
 // Usage:
 //   bool = all_defined(v, [recursive]);
 // Description:
@@ -551,6 +585,9 @@ function all_defined(v,recursive=false) =
 // Section: Undef Safe Arithmetic
 
 // Function: u_add()
+// Synopsis: Returns the sum of 2 numbers if both are defined, otherwise returns undef.
+// Topics: Undef Handling
+// See Also: u_sub(), u_mul(), u_div()
 // Usage:
 //   x = u_add(a, b);
 // Description:
@@ -563,6 +600,9 @@ function u_add(a,b) = is_undef(a) || is_undef(b)? undef : a + b;
 
 
 // Function: u_sub()
+// Synopsis: Returns the difference of 2 numbers if both are defined, otherwise returns undef.
+// Topics: Undef Handling
+// See Also: u_add(), u_mul(), u_div()
 // Usage:
 //   x = u_sub(a, b);
 // Description:
@@ -575,6 +615,9 @@ function u_sub(a,b) = is_undef(a) || is_undef(b)? undef : a - b;
 
 
 // Function: u_mul()
+// Synopsis: Returns the product of 2 numbers if both are defined, otherwise returns undef.
+// Topics: Undef Handling
+// See Also: u_add(), u_sub(), u_div()
 // Usage:
 //   x = u_mul(a, b);
 // Description:
@@ -590,6 +633,9 @@ function u_mul(a,b) =
 
 
 // Function: u_div()
+// Synopsis: Returns the quotient of 2 numbers if both are defined, otherwise returns undef.
+// Topics: Undef Handling
+// See Also: u_add(), u_sub(), u_mul()
 // Usage:
 //   x = u_div(a, b);
 // Description:
@@ -610,10 +656,11 @@ function u_div(a,b) =
 
 
 // Function: get_anchor()
-// Usage:
-//   anchr = get_anchor(anchor,center,[uncentered],[dflt]);
+// Synopsis: Returns the correct anchor from `anchor` and `center`.
 // Topics: Argument Handling
 // See Also: get_radius()
+// Usage:
+//   anchr = get_anchor(anchor,center,[uncentered],[dflt]);
 // Description:
 //   Calculated the correct anchor from `anchor` and `center`.  In order:
 //   - If `center` is not `undef` and `center` evaluates as true, then `CENTER` (`[0,0,0]`) is returned.
@@ -640,10 +687,11 @@ function get_anchor(anchor,center,uncentered=BOT,dflt=CENTER) =
 
 
 // Function: get_radius()
-// Usage:
-//   r = get_radius([r1=], [r2=], [r=], [d1=], [d2=], [d=], [dflt=]);
+// Synopsis: Given various radii and diameters, returns the most specific radius.
 // Topics: Argument Handling
 // See Also: get_anchor()
+// Usage:
+//   r = get_radius([r1=], [r2=], [r=], [d1=], [d2=], [d=], [dflt=]);
 // Description:
 //   Given various radii and diameters, returns the most specific radius.  If a diameter is most
 //   specific, returns half its value, giving the radius.  If no radii or diameters are defined,
@@ -688,10 +736,11 @@ function get_radius(r1, r2, r, d1, d2, d, dflt) =
 
 
 // Function: scalar_vec3()
-// Usage:
-//   vec = scalar_vec3(v, [dflt]);
+// Synopsis: Expands a scalar or a list with length less than 3 to a length 3 vector. 
 // Topics: Argument Handling
 // See Also: get_anchor(), get_radius(), force_list()
+// Usage:
+//   vec = scalar_vec3(v, [dflt]);
 // Description:
 //   This is expands a scalar or a list with length less than 3 to a length 3 vector in the
 //   same way that OpenSCAD expands short vectors in some contexts, e.g. cube(10) or rotate([45,90]).  
@@ -717,9 +766,10 @@ function scalar_vec3(v, dflt) =
 
 
 // Function: segs()
+// Synopsis: Returns the number of sides for a circle given `$fn`, `$fa`, and `$fs`.
+// Topics: Geometry
 // Usage:
 //   sides = segs(r);
-// Topics: Geometry
 // Description:
 //   Calculate the standard number of sides OpenSCAD would give a circle based on `$fn`, `$fa`, and `$fs`.
 // Arguments:
@@ -734,10 +784,11 @@ function segs(r) =
 
 
 // Module: no_children()
-// Usage:
-//   no_children($children);
+// Synopsis: Assert that the calling module does not support children.
 // Topics: Error Checking
 // See Also: no_function(), no_module(), req_children()
+// Usage:
+//   no_children($children);
 // Description:
 //   Assert that the calling module does not support children.  Prints an error message to this effect and fails if children are present,
 //   as indicated by its argument.
@@ -756,10 +807,11 @@ module no_children(count) {
 
 
 // Module: req_children()
-// Usage:
-//   req_children($children);
+// Assert that the calling module requires children.
 // Topics: Error Checking
 // See Also: no_function(), no_module()
+// Usage:
+//   req_children($children);
 // Description:
 //   Assert that the calling module requires children.  Prints an error message and fails if no
 //   children are present as indicated by its argument.
@@ -778,6 +830,7 @@ module req_children(count) {
 
 
 // Function: no_function()
+// Synopsis: Assert that the argument exists only as a module and not as a function.
 // Usage:
 //   dummy = no_function(name)
 // Topics: Error Checking
@@ -791,10 +844,11 @@ function no_function(name) =
 
 
 // Module: no_module()
-// Usage:
-//   no_module();
+// Synopsis: Assert that the argument exists only as a function and not as a module.
 // Topics: Error Checking
 // See Also: no_children(), no_function()
+// Usage:
+//   no_module();
 // Description:
 //   Asserts that the called module exists only as a function.
 // Example:
@@ -805,6 +859,7 @@ module no_module() {
   
 
 // Module: deprecate()
+// Synopsis: Display a console note that a module is deprecated and suggest a replacement.
 // Usage:
 //   deprecate(new_name);
 // Description:
@@ -828,14 +883,17 @@ function _valstr(x) =
 
 
 // Module: assert_approx()
-// Usage:
-//   assert_approx(got, expected, [info]);
+// Synopsis: Assert that a value is approximately what was expected.
 // Topics: Error Checking, Debugging
 // See Also: no_children(), no_function(), no_module(), assert_equal()
+// Usage:
+//   assert_approx(got, expected, [info]);
 // Description:
-//   Tests if the value gotten is what was expected.  If not, then
+//   Tests if the value gotten is what was expected, plus or minus 1e-9.  If not, then
 //   the expected and received values are printed to the console and
 //   an assertion is thrown to stop execution.
+//   
+//   Returns false if both 'got' and 'expected' are 'nan'.
 // Arguments:
 //   got = The value actually received.
 //   expected = The value that was expected.
@@ -860,13 +918,16 @@ module assert_approx(got, expected, info) {
 
 
 // Module: assert_equal()
+// Synopsis: Assert that a value is expected.
+// See Also: no_children(), no_function(), no_module(), assert_approx()
+// Topics: Error Checking, Debugging
 // Usage:
 //   assert_equal(got, expected, [info]);
-// Topics: Error Checking, Debugging
-// See Also: no_children(), no_function(), no_module(), assert_approx()
 // Description:
 //   Tests if the value gotten is what was expected.  If not, then the expected and received values
 //   are printed to the console and an assertion is thrown to stop execution.
+//   
+//   Returns true if both 'got' and 'expected' are 'nan'.
 // Arguments:
 //   got = The value actually received.
 //   expected = The value that was expected.
@@ -891,10 +952,12 @@ module assert_equal(got, expected, info) {
 
 
 // Module: shape_compare()
-// Usage:
-//   shape_compare([eps]) {TEST_SHAPE; EXPECTED_SHAPE;}
+// Synopsis: Compares two child shapes.
+// SynTags: Geom
 // Topics: Error Checking, Debugging, Testing
 // See Also: assert_approx(), assert_equal()
+// Usage:
+//   shape_compare([eps]) {TEST_SHAPE; EXPECTED_SHAPE;}
 // Description:
 //   Compares two child shapes, returning empty geometry if they are very nearly the same shape and size.
 //   Returns the differential geometry if they are not quite the same shape and size.
@@ -972,10 +1035,11 @@ module shape_compare(eps=1/1024) {
 
 
 // Function: looping()
-// Usage:
-//   bool = looping(state);
+// Synopsis: Returns true if the argument indicates the current C-style loop should continue.
 // Topics: Iteration
 // See Also: loop_while(), loop_done()
+// Usage:
+//   bool = looping(state);
 // Description:
 //   Returns true if the `state` value indicates the current loop should continue.  This is useful
 //   when using C-style for loops to iteratively calculate a value.  Used with `loop_while()` and
@@ -986,10 +1050,11 @@ function looping(state) = state < 2;
 
 
 // Function: loop_while()
-// Usage:
-//   state = loop_while(state, continue);
+// Synopsis: Returns true if both arguments indicate the current C-style loop should continue.
 // Topics: Iteration
 // See Also: looping(), loop_done()
+// Usage:
+//   state = loop_while(state, continue);
 // Description:
 //   Given the current `state`, and a boolean `continue` that indicates if the loop should still be
 //   continuing, returns the updated state value for the the next loop.  This is useful when using
@@ -1004,10 +1069,11 @@ function loop_while(state, continue) =
 
 
 // Function: loop_done()
-// Usage:
-//   bool = loop_done(state);
+// Synopsis: Returns true if the argument indicates the current C-style loop is finishing.
 // Topics: Iteration
 // See Also: looping(), loop_while()
+// Usage:
+//   bool = loop_done(state);
 // Description:
 //   Returns true if the `state` value indicates the loop is finishing.  This is useful when using
 //   C-style for loops to iteratively calculate a value.  Used with `looping()` and `loop_while()`.