diff --git a/comparisons.scad b/comparisons.scad index 8ecc382..1687f12 100644 --- a/comparisons.scad +++ b/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 diff --git a/transforms.scad b/transforms.scad index ae5da9f..2e98474 100644 --- a/transforms.scad +++ b/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 diff --git a/utility.scad b/utility.scad index b321cf0..07be785 100644 --- a/utility.scad +++ b/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()`.