Fixed a bunch of docs errors with Usage headers.

affine.scad

@@ -399,7 +399,8 @@ function affine3d_chain(affines, _m=undef, _i=0) =
 
 
 // Function: apply()
-// Usage: apply(transform, points)
+// Usage:
+//   pts = apply(transform, points)
 // Description:
 //   Applies the specified transformation matrix to a point list (or single point).  Both inputs can be 2d or 3d, and it is also allowed
 //   to supply 3d transformations with 2d data as long as the the only action on the z coordinate is a simple scaling.  
@@ -423,7 +424,8 @@ function apply(transform,points) =
 
 
 // Function: apply_list()
-// Usage: apply_list(points, transform_list)
+// Usage:
+//   pts = apply_list(points, transform_list)
 // Description:
 //   Transforms the specified point list (or single point) using a list of transformation matrices.  Transformations on
 //   the list are applied in the order they appear in the list (as in right multiplication of matrices).  Both inputs can be

arrays.scad

@@ -1146,7 +1146,8 @@ function subindex(M, idx) =
 
 
 // Function: submatrix()
-// Usage: submatrix(M, idx1, idx2)
+// Usage:
+//   mat = submatrix(M, idx1, idx2)
 // Description:
 //   The input must be a list of lists (a matrix or 2d array).  Returns a submatrix by selecting the rows listed in idx1 and columns listed in idx2.
 // Arguments:
@@ -1245,7 +1246,8 @@ function diagonal_matrix(diag,offdiag=0) =
 
 
 // Function: submatrix_set()
-// Usage: submatrix_set(M,A,[m],[n])
+// Usage:
+//   mat = submatrix_set(M,A,[m],[n])
 // Description:
 //    Sets a submatrix of M equal to the matrix A.  By default the top left corner of M is set to A, but
 //    you can specify offset coordinates m and n.  If A (as adjusted by m and n) extends beyond the bounds

geometry.scad

@@ -1443,7 +1443,8 @@ function circle_point_tangents(r, d, cp, pt) =
 
 
 // Function: circle_circle_tangents()
-// Usage: circle_circle_tangents(c1, r1|d1, c2, r2|d2)
+// Usage:
+//   segs = circle_circle_tangents(c1, r1|d1, c2, r2|d2);
 // Description:
 //   Computes 2d lines tangents to a pair of circles in 2d.  Returns a list of line endpoints [p1,p2] where
 //   p2 is the tangent point on circle 1 and p2 is the tangent point on circle 2.

math.scad

@@ -731,7 +731,8 @@ function null_space(A,eps=1e-12) =
 
 
 // Function: qr_factor()
-// Usage: qr = qr_factor(A,[pivot])
+// Usage:
+//   qr = qr_factor(A,[pivot]);
 // Description:
 //   Calculates the QR factorization of the input matrix A and returns it as the list [Q,R,P].  This factorization can be
 //   used to solve linear systems of equations.  The factorization is A = Q*R*transpose(P).  If pivot is false (the default)
@@ -780,7 +781,8 @@ function _swap_matrix(n,i,j) =
 
 
 // Function: back_substitute()
-// Usage: back_substitute(R, b, <transpose>)
+// Usage:
+//   x = back_substitute(R, b, <transpose>);
 // Description:
 //   Solves the problem Rx=b where R is an upper triangular square matrix.  The lower triangular entries of R are
 //   ignored.  If transpose==true then instead solve transpose(R)*x=b.

paths.scad

@@ -316,7 +316,8 @@ function path_closest_point(path, pt) =
 
 
 // Function: path_tangents()
-// Usage: path_tangents(path, [closed], [uniform])
+// Usage:
+//   tangs = path_tangents(path, <closed>, <uniform>);
 // Description:
 //   Compute the tangent vector to the input path.  The derivative approximation is described in deriv().
 //   The returns vectors will be normalized to length 1.  If any derivatives are zero then
@@ -348,7 +349,8 @@ function path_tangents(path, closed=false, uniform=true) =
 
 
 // Function: path_normals()
-// Usage:  path_normals(path, [tangents], [closed])
+// Usage:
+//   norms = path_normals(path, <tangents>, <closed>);
 // Description:
 //   Compute the normal vector to the input path.  This vector is perpendicular to the
 //   path tangent and lies in the plane of the curve.  When there are collinear points,
@@ -371,7 +373,8 @@ function path_normals(path, tangents, closed=false) =
 
 
 // Function: path_curvature()
-// Usage: path_curvature(path, [closed])
+// Usage:
+//   curvs = path_curvature(path, <closed>);
 // Description:
 //   Numerically estimate the curvature of the path (in any dimension). 
 function path_curvature(path, closed=false) =
@@ -388,7 +391,8 @@ function path_curvature(path, closed=false) =
 
 
 // Function: path_torsion()
-// Usage: path_torsion(path, [closed])
+// Usage:
+//   tortions = path_torsion(path, <closed>);
 // Description:
 //   Numerically estimate the torsion of a 3d path.  
 function path_torsion(path, closed=false) =
@@ -1290,7 +1294,8 @@ function subdivide_path(path, N, refine, closed=true, exact=true, method="length
 
 
 // Function: path_length_fractions()
-// Usage: path_length_fractions(path, [closed])
+// Usage:
+//   fracs = path_length_fractions(path, <closed>);
 // Description:
 //    Returns the distance fraction of each point in the path along the path, so the first
 //    point is zero and the final point is 1.  If the path is closed the length of the output
@@ -1311,7 +1316,8 @@ function path_length_fractions(path, closed=false) =
 
 
 // Function: resample_path()
-// Usage: resample_path(path, N|spacing, [closed])
+// Usage:
+//   newpath = resample_path(path, N|spacing, <closed>);
 // Description:
 //   Compute a uniform resampling of the input path.  If you specify `N` then the output path will have N
 //   points spaced uniformly (by linear interpolation along the input path segments).  The only points of the

polyhedra.scad

@@ -543,7 +543,8 @@ _stellated_polyhedra_ = [
 
 // Function: regular_polyhedron_info()
 //
-// Usage: regular_polyhedron_info(info, ....)
+// Usage:
+//   x = regular_polyhedron_info(info, ....);
 //
 // Description:
 //   Calculate characteristics of regular polyhedra or the selection set for regular_polyhedron().

scripts/docs_gen.py

@@ -405,6 +405,10 @@ class LeafNode(object):
                 dummy, title = line.split(":", 1)
                 title = title.strip()
                 lines, block = get_comment_block(lines, prefix)
+                if block == []:
+                    print("Error: Usage header without any usage examples.")
+                    print(line)
+                    sys.exit(-2)
                 self.usages.append([title, block])
                 continue
             if line.startswith("Description:"):

skin.scad

@@ -512,8 +512,9 @@ function subdivide_and_slice(profiles, slices, numpoints, method="length", close
   slice_profiles(fixpoly, slices, closed);
   
 
-// Function slice_profiles()
-// Usage: slice_profiles(profiles,slices,[closed])
+// Function: slice_profiles()
+// Usage:
+//   profs = slice_profiles(profiles,slices,<closed>);
 // Description:
 //   Given an input list of profiles, linearly interpolate between each pair to produce a
 //   more finely sampled list.  The parameters `slices` specifies the number of slices to
@@ -640,7 +641,8 @@ function _dp_extract_map(map) =
      
 
 // Internal Function: _skin_distance_match(poly1,poly2)
-// Usage: _skin_distance_match(poly1,poly2)
+// Usage:
+//   polys = _skin_distance_match(poly1,poly2);
 // Description:
 //   Find a way of associating the vertices of poly1 and vertices of poly2
 //   that minimizes the sum of the length of the edges that connect the two polygons.
@@ -686,16 +688,17 @@ function _skin_distance_match(poly1,poly2) =
 //////////////////////////////////////////////////////////////////////////////////////////////////////////////
 //
 // Internal Function: _skin_tangent_match()
-// Usage: _skin_tangent_match(poly1, poly2)
+// Usage:
+//   x = _skin_tangent_match(poly1, poly2)
 // Description:
-//    Finds a mapping of the vertices of the larger polygon onto the smaller one.  Whichever input is the
-//    shorter path is the polygon, and the longer input is the curve.  For every edge of the polygon, the algorithm seeks a plane that contains that
-//    edge and is tangent to the curve.  There will be more than one such point.  To choose one, the algorithm centers the polygon and curve on their centroids
-//    and chooses the closer tangent point.  The algorithm works its way around the polygon, computing a series of tangent points and then maps all of the
-//    points on the curve between two tangent points into one vertex of the polygon.  This algorithm can fail if the curve has too few points or if it is concave.
+//   Finds a mapping of the vertices of the larger polygon onto the smaller one.  Whichever input is the
+//   shorter path is the polygon, and the longer input is the curve.  For every edge of the polygon, the algorithm seeks a plane that contains that
+//   edge and is tangent to the curve.  There will be more than one such point.  To choose one, the algorithm centers the polygon and curve on their centroids
+//   and chooses the closer tangent point.  The algorithm works its way around the polygon, computing a series of tangent points and then maps all of the
+//   points on the curve between two tangent points into one vertex of the polygon.  This algorithm can fail if the curve has too few points or if it is concave.
 // Arguments:
-//    poly1 = input polygon
-//    poly2 = input polygon
+//   poly1 = input polygon
+//   poly2 = input polygon
 function _skin_tangent_match(poly1, poly2) =
     let(
         swap = len(poly1)>len(poly2),
@@ -794,7 +797,10 @@ function associate_vertices(polygons, split, curpoly=0) =
 
 
 // Function&Module: sweep()
-// Usage: sweep(shape, transformations, [closed], [caps])
+// Usage: As Module
+//   sweep(shape, transformations, <closed<, <caps>)
+// Usage: As Function
+//   vnf = sweep(shape, transformations, <closed>, <caps>);
 // Description:
 //   The input `shape` must be a non-self-intersecting polygon in two dimensions, and `transformations`
 //   is a list of 4x4 transformation matrices.  The sweep algorithm applies each transformation in sequence

version.scad

@@ -8,7 +8,7 @@
 //////////////////////////////////////////////////////////////////////
 
 
-BOSL_VERSION = [2,0,437];
+BOSL_VERSION = [2,0,438];
 
 
 // Section: BOSL Library Version Functions