From 38873d8ef9c90667572b77808599d94613331142 Mon Sep 17 00:00:00 2001 From: Garth Minette Date: Sat, 3 Oct 2020 20:29:35 -0700 Subject: [PATCH] Fixed a bunch of docs errors with Usage headers. --- affine.scad | 6 ++++-- arrays.scad | 6 ++++-- geometry.scad | 3 ++- math.scad | 6 ++++-- paths.scad | 18 ++++++++++++------ polyhedra.scad | 3 ++- scripts/docs_gen.py | 4 ++++ skin.scad | 30 ++++++++++++++++++------------ version.scad | 2 +- 9 files changed, 51 insertions(+), 27 deletions(-) diff --git a/affine.scad b/affine.scad index b39529f..5696cc6 100644 --- a/affine.scad +++ b/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 diff --git a/arrays.scad b/arrays.scad index 9ba0850..e23ef7b 100644 --- a/arrays.scad +++ b/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 diff --git a/geometry.scad b/geometry.scad index 0832644..b95a4e9 100644 --- a/geometry.scad +++ b/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. diff --git a/math.scad b/math.scad index 759fe7e..0c847b8 100644 --- a/math.scad +++ b/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, ) +// Usage: +// x = back_substitute(R, b, ); // 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. diff --git a/paths.scad b/paths.scad index c94d933..e0e7c95 100644 --- a/paths.scad +++ 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, , ); // 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, , ); // 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, ); // 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, ); // 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, ); // 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, ); // 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 diff --git a/polyhedra.scad b/polyhedra.scad index 13cbe54..bdcd87e 100644 --- a/polyhedra.scad +++ b/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(). diff --git a/scripts/docs_gen.py b/scripts/docs_gen.py index 5d38829..044fd64 100755 --- a/scripts/docs_gen.py +++ b/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:"): diff --git a/skin.scad b/skin.scad index 87ae8d4..be18010 100644 --- a/skin.scad +++ b/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,); // 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, ) +// Usage: As Function +// vnf = sweep(shape, transformations, , ); // 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 diff --git a/version.scad b/version.scad index 447b3e7..8712a4a 100644 --- a/version.scad +++ b/version.scad @@ -8,7 +8,7 @@ ////////////////////////////////////////////////////////////////////// -BOSL_VERSION = [2,0,437]; +BOSL_VERSION = [2,0,438]; // Section: BOSL Library Version Functions