usage messages fixes and some arg tweaks

coords.scad

@@ -20,7 +20,7 @@
 //   Returns a 2D vector/point from a 2D or 3D vector.  If given a 3D point, removes the Z coordinate.
 // Arguments:
 //   p = The coordinates to force into a 2D vector/point.
-//   fill = Value to fill missing values in vector with.
+//   fill = Value to fill missing values in vector with.  Default: 0
 function point2d(p, fill=0) = assert(is_list(p)) [for (i=[0:1]) (p[i]==undef)? fill : p[i]];
 
 
@@ -51,7 +51,7 @@ function path2d(points) =
 //   Returns a 3D vector/point from a 2D or 3D vector.
 // Arguments:
 //   p = The coordinates to force into a 3D vector/point.
-//   fill = Value to fill missing values in vector with.
+//   fill = Value to fill missing values in vector with.  Default: 0
 function point3d(p, fill=0) =
     assert(is_list(p)) 
     [for (i=[0:2]) (p[i]==undef)? fill : p[i]];
@@ -67,7 +67,7 @@ function point3d(p, fill=0) =
 //   by removing extra coordinates or adding the z coordinate.  
 // Arguments:
 //   points = A list of 2D, 3D or higher dimensional points/vectors.
-//   fill = Value to fill missing values in vectors with (in the 2D case)
+//   fill = Value to fill missing values in vectors with (in the 2D case).  Default: 0
 function path3d(points, fill=0) =
     assert(is_num(fill))
     assert(is_path(points, dim=undef, fast=true), "Input to path3d is not a path")
@@ -90,7 +90,7 @@ function path3d(points, fill=0) =
 //   Returns a 4D vector/point from a 2D or 3D vector.
 // Arguments:
 //   p = The coordinates to force into a 4D vector/point.
-//   fill = Value to fill missing values in vector with.
+//   fill = Value to fill missing values in vector with.  Default: 0
 function point4d(p, fill=0) = assert(is_list(p))
                               [for (i=[0:3]) (p[i]==undef)? fill : p[i]];
 
@@ -104,7 +104,7 @@ function point4d(p, fill=0) = assert(is_list(p))
 //   Returns a list of 4D vectors/points from a list of 2D or 3D vectors/points.
 // Arguments:
 //   points = A list of 2D or 3D points/vectors.
-//   fill = Value to fill missing values in vectors with.
+//   fill = Value to fill missing values in vectors with.  Default: 0 
 function path4d(points, fill=0) = 
    assert(is_num(fill) || is_vector(fill))
    assert(is_path(points, dim=undef, fast=true), "Input to path4d is not a path")

lists.scad

@@ -19,7 +19,7 @@
 // Function: is_homogeneous()
 // Alias: is_homogenous()
 // Usage:
-//   bool = is_homogeneous(list, depth);
+//   bool = is_homogeneous(list, [depth]);
 // Topics: List Handling, Type Checking
 // See Also: is_vector(), is_matrix()
 // Description:
@@ -27,7 +27,7 @@
 //   Booleans and numbers are not distinguinshed as of distinct types. 
 // Arguments:
 //   l = the list to check
-//   depth = the lowest level the check is done
+//   depth = the lowest level the check is done.  Default: 10
 // Example:
 //   a = is_homogeneous([[1,["a"]], [2,["b"]]]);     // Returns true
 //   b = is_homogeneous([[1,["a"]], [2,[true]]]);    // Returns false
@@ -233,8 +233,8 @@ function select(list, start, end) =
 //   An index of -1 refers to the last list item.
 // Arguments:
 //   list = The list to get the slice of.
-//   s = The index of the first item to return.
+//   start = The index of the first item to return.  Default: 0
-//   e = The index of the last item to return.
+//   end = The index of the last item to return.  Default: -1 (last item)
 // See Also: select(), column(), last()
 // Example:
 //   a = slice([3,4,5,6,7,8,9], 3, 5);   // Returns [6,7,8]
@@ -243,17 +243,17 @@ function select(list, start, end) =
 //   d = slice([3,4,5,6,7,8,9], 5);      // Returns [8,9]
 //   e = slice([3,4,5,6,7,8,9], 2, -2);  // Returns [5,6,7,8]
 //   f = slice([3,4,5,6,7,8,9], 4, 3;    // Returns []
-function slice(list,s=0,e=-1) =
+function slice(list,start=0,end=-1) =
     assert(is_list(list))
-    assert(is_int(s))
+    assert(is_int(start))
-    assert(is_int(e))
+    assert(is_int(eend))
     !list? [] :
     let(
         l = len(list),
-        s = constrain(s + (s<0? l : 0), 0, l-1),
+        start = constrain(start + (start<0? l : 0), 0, l-1),
-        e = constrain(e + (e<0? l : 0), 0, l-1)
+        end = constrain(end + (end<0? l : 0), 0, l-1)
     )
-    [if (e>=s) for (i=[s:1:e]) list[i]];
+    [if (end>=start) for (i=[start:1:end]) list[i]];
 
 
 // Function: last()
@@ -279,12 +279,13 @@ function last(list) =
 // See Also: select(), slice(), list_tail(), last()
 // Description:
 //   Returns the head of the given list, from the first item up until the `to` index, inclusive.
+//   By default returns all but the last element of the list.  
 //   If the `to` index is negative, then the length of the list is added to it, such that
 //   `-1` is the last list item.  `-2` is the second from last.  `-3` is third from last, etc.
 //   If the list is shorter than the given index, then the full list is returned.
 // Arguments:
 //   list = The list to get the head of.
-//   to = The last index to include.  If negative, adds the list length to it.  ie: -1 is the last list item.
+//   to = The last index to include.  If negative, adds the list length to it.  ie: -1 is the last list item.  Default: -2
 // Example:
 //   hlist1 = list_head(["foo", "bar", "baz"]);  // Returns: ["foo", "bar"]
 //   hlist2 = list_head(["foo", "bar", "baz"], -3); // Returns: ["foo"]
@@ -306,12 +307,13 @@ function list_head(list, to=-2) =
 // See Also: select(), slice(), list_tail(), last()
 // Description:
 //   Returns the tail of the given list, from the `from` index up until the end of the list, inclusive.
+//   By default returns all but the first item.  
 //   If the `from` index is negative, then the length of the list is added to it, such that
 //   `-1` is the last list item.  `-2` is the second from last.  `-3` is third from last, etc.
 //   If you want it to return the last three items of the list, use `from=-3`.
 // Arguments:
 //   list = The list to get the tail of.
-//   from = The first index to include.  If negative, adds the list length to it.  ie: -1 is the last list item.
+//   from = The first index to include.  If negative, adds the list length to it.  ie: -1 is the last list item.  Default: 1.
 // Example:
 //   tlist1 = list_tail(["foo", "bar", "baz"]);  // Returns: ["bar", "baz"]
 //   tlist2 = list_tail(["foo", "bar", "baz"], -1); // Returns: ["baz"]
@@ -364,7 +366,7 @@ function bselect(list,index) =
 //   multi-dimensional array, filled with `val`.
 // Arguments:
 //   val = The value to repeat to make the list or array.
-//   n = The number of copies to make of `val`.
+//   n = The number of copies to make of `val`.  Can be a list to make an array of copies.
 // Example:
 //   a = repeat(1, 4);        // Returns [1,1,1,1]
 //   b = repeat(8, [2,3]);    // Returns [[8,8,8], [8,8,8]]
@@ -391,7 +393,7 @@ function repeat(val, n, i=0) =
 // Arguments:
 //   indexset = A list of boolean values.
 //   valuelist = The list of values to set into the returned list.
-//   dflt = Default value to store when the indexset item is false.
+//   dflt = Default value to store when the indexset item is false.  Default: 0
 // Example:
 //   a = list_bset([false,true,false,true,false], [3,4]);  // Returns: [0,3,0,4,0]
 //   b = list_bset([false,true,false,true,false], [3,4], dflt=1);  // Returns: [1,3,1,4,1]
@@ -461,13 +463,13 @@ function force_list(value, n=1, fill) =
 // Description:
 //   Reverses a list or string.
 // Arguments:
-//   x = The list or string to reverse.
+//   list = The list or string to reverse.
 // Example:
 //   reverse([3,4,5,6]);  // Returns [6,5,4,3]
-function reverse(x) =
+function reverse(list) =
-    assert(is_list(x)||is_string(x), str("Input to reverse must be a list or string. Got: ",x))
+    assert(is_list(list)||is_string(list), str("Input to reverse must be a list or string. Got: ",list))
-    let (elems = [ for (i = [len(x)-1 : -1 : 0]) x[i] ])
+    let (elems = [ for (i = [len(list)-1 : -1 : 0]) list[i] ])
-    is_string(x)? str_join(elems) : elems;
+    is_string(list)? str_join(elems) : elems;
 
 
 // Function: list_rotate()
@@ -652,7 +654,12 @@ function list_set(list=[],indices,values,dflt=0,minlen=0) =
 // Topics: List Handling
 // See Also: list_set(), list_remove(), list_remove_values()
 // Description:
-//   Insert `values` into `list` before position `indices`.
+//   Insert `values` into `list` before position `indices`.  The indices for insertion 
+//   are based on the original list, before any insertions have occurred.  
+// Arguments:
+//   list = list to insert items into
+//   indices = index or list of indices where values are inserted
+//   values = value or list of values to insert
 // Example:
 //   a = list_insert([3,6,9,12],1,5);  // Returns [3,5,6,9,12]
 //   b = list_insert([3,6,9,12],[1,3],[5,11]);  // Returns [3,5,6,9,11,12]
@@ -729,8 +736,7 @@ function list_remove(list, ind) =
 
 // Function: list_remove_values()
 // Usage:
-//   list = list_remove_values(list, values);
+//   list = list_remove_values(list, values, [all]);
-//   list = list_remove_values(list, values, all=true);
 // Topics: List Handling
 // See Also: list_set(), list_insert(), list_remove()
 // Description:
@@ -806,6 +812,7 @@ function list_remove_values(list,values=[],all=false) =
 //   Returns the range of indexes for the given list.
 // Arguments:
 //   list = The list to returns the index range of.
+//   ---
 //   s = The starting index.  Default: 0
 //   e = The delta from the end of the list.  Default: -1 (end of list)
 //   step = The step size to stride through the list.  Default: 1
@@ -906,7 +913,7 @@ function triplet(list, wrap=false) =
 //   For the list `[1,2,3,4]`, with `n=3`, this will return `[[1,2,3], [1,2,4], [1,3,4], [2,3,4]]`.
 // Arguments:
 //   l = The list to provide permutations for.
-//   n = The number of items in each permutation. Default: 2
+//   n = The number of items in each combination. Default: 2
 // Example:
 //   pairs = combinations([3,4,5,6]);  // Returns: [[3,4],[3,5],[3,6],[4,5],[4,6],[5,6]]
 //   triplets = combinations([3,4,5,6],n=3);  // Returns: [[3,4,5],[3,4,6],[3,5,6],[4,5,6]]

strings.scad

@@ -56,7 +56,7 @@ function suffix(str,len) =
 
 // Function: str_find()
 // Usage:
-//   str_find(str,pattern,[last],[all],[start])
+//   str_find(str,pattern,[last=],[all=],[start=])
 // Description:
 //   Searches input string `str` for the string `pattern` and returns the index or indices of the matches in `str`.
 //   By default `str_find()` returns the index of the first match in `str`.  If `last` is true then it returns the index of the last match.
@@ -67,6 +67,7 @@ function suffix(str,len) =
 // Arguments:
 //   str = String to search.
 //   pattern = string pattern to search for
+//   ---
 //   last = set to true to return the last match. Default: false
 //   all = set to true to return all matches as a list.  Overrides last.  Default: false  
 //   start = index where the search starts
@@ -402,7 +403,7 @@ function parse_float(str) =
 
 // Function: parse_frac()
 // Usage:
-//   parse_frac(str,[mixed],[improper],[signed])
+//   parse_frac(str,[mixed=],[improper=],[signed=])
 // Description:
 //   Converts a string fraction to a floating point number.  A string fraction has the form `[-][# ][#/#]` where each `#` is one or more of the
 //   digits 0-9, and there is an optional sign character at the beginning. 
@@ -414,6 +415,7 @@ function parse_float(str) =
 //   The empty string evaluates to zero.  Any invalid string evaluates to NaN.    
 // Arguments:
 //   str = String to convert.
+//   ---
 //   mixed = set to true to accept mixed fractions, false to reject them.  Default: true  
 //   improper = set to true to accept improper fractions, false to reject them.  Default: true
 //   signed = set to true to accept a leading sign character, false to reject.  Default: true  

structs.scad

@@ -94,22 +94,22 @@ function struct_val(struct, key, default=undef) =
 function struct_keys(struct) = column(struct,0);
 
 
-// Function&Module: struct_echo()
+// Function&Module: echo_struct()
 // Usage:
-//   struct_echo(struct, [name])
+//   echo_struct(struct, [name])
 // Description:
 //   Displays a list of structure keys and values, one pair per line, for easier reading.
 // Arguments:
 //   struct = input structure
 //   name = optional structure name to list at the top of the output.  Default: ""
-function struct_echo(struct,name="") =
+function echo_struct(struct,name="") =
     let( keylist = [for(entry=struct) str("  ",entry[0],": ",entry[1],"\n")])
     echo(str("\nStructure ",name,"\n",str_join(keylist)))
     undef;
 
-module struct_echo(struct,name="") {
+module echo_struct(struct,name="") {
     no_children($children);
-    dummy = struct_echo(struct,name);
+    dummy = echo_struct(struct,name);
 }
 
 

tests/test_structs.scad

@@ -60,10 +60,10 @@ module test_struct_keys() {
 test_struct_keys();
 
 
-module test_struct_echo() {
+module test_echo_struct() {
     // Can't yet test echo output
 }
-test_struct_echo();
+test_echo_struct();
 
 
 module test_is_struct() {

version.scad

@@ -52,18 +52,20 @@ function bosl_version_str() = version_to_str(BOSL_VERSION);
 
 // Module: bosl_required()
 // Usage:
-//   bosl_required(x);
+//   bosl_required(version);
 // Topics: Versioning
 // Description:
 //   Given a version as a list, number, or string, asserts that the currently installed BOSL library is at least the given version.
 // See Also: version_to_num(), version_to_str(), version_to_list(), version_cmp()
-module bosl_required(target) {
+// Arguments:
+//   version = version required
+module bosl_required(version) {
     no_children($children);
     assert(
-        version_cmp(bosl_version(), target) >= 0,
+        version_cmp(bosl_version(), version) >= 0,
         str(
             "BOSL ", bosl_version_str(), " is installed, but BOSL ",
-            version_to_str(target), " or better is required."  
+            version_to_str(version), " or better is required."  
         )
     );
 }
@@ -89,50 +91,56 @@ function _version_split_str(x, _i=0, _out=[], _num=0) =
 // Description:
 //   Given a version string, number, or list, returns the list of version integers [MAJOR,MINOR,REVISION].
 // See Also: version_to_num(), version_to_str(), version_cmp(), bosl_required()
+// Arguments:
+//   x = version to convert
 // Example:
 //   v1 = version_to_list("2.1.43");  // Returns: [2,1,43]
 //   v2 = version_to_list(2.120234);  // Returns: [2,12,234]
 //   v3 = version_to_list([2,3,4]);   // Returns: [2,3,4]
 //   v4 = version_to_list([2,3,4,5]); // Returns: [2,3,4]
-function version_to_list(x) =
+function version_to_list(version) =
-    is_list(x)? [default(x[0],0), default(x[1],0), default(x[2],0)] :
+    is_list(version)? [default(version[0],0), default(version[1],0), default(version[2],0)] :
-    is_string(x)? _version_split_str(x) :
+    is_string(version)? _version_split_str(version) :
-    is_num(x)? [floor(x), floor(x*100%100), floor(x*1000000%10000+0.5)] :
+    is_num(version)? [floor(version), floor(version*100%100), floor(version*1000000%10000+0.5)] :
-    assert(is_num(x) || is_vector(x) || is_string(x)) 0;
+    assert(is_num(version) || is_vector(version) || is_string(version)) 0;
 
 
 // Function: version_to_str()
 // Usage:
-//   str = version_to_str(x);
+//   str = version_to_str(version);
 // Topics: Versioning
 // Description:
 //   Takes a version string, number, or list, and returns the properly formatter version string for it.
 // See Also: version_to_num(), version_to_list(), version_cmp(), bosl_required()
+// Arguments:
+//   version = version to convert
 // Example:
 //   v1 = version_to_str([2,1,43]);  // Returns: "2.1.43"
 //   v2 = version_to_str(2.010043);  // Returns: "2.1.43"
 //   v3 = version_to_str(2.340789);  // Returns: "2.34.789"
 //   v4 = version_to_str("2.3.89");  // Returns: "2.3.89"
-function version_to_str(x) =
+function version_to_str(version) =
-    let(x = version_to_list(x))
+    let(version = version_to_list(version))
-    str(x[0],".",x[1],".",x[2]);
+    str(version[0],".",version[1],".",version[2]);
 
 
 // Function: version_to_num()
 // Usage:
-//   str = version_to_num(x);
+//   str = version_to_num(version);
 // Topics: Versioning
 // Description:
 //   Takes a version string, number, or list, and returns the properly formatter version number for it.
 // See Also: version_cmp(), version_to_str(), version_to_list(), bosl_required()
+// Arguments:
+//   version = version to convert
 // Example:
 //   v1 = version_to_num([2,1,43]);   // Returns: 2.010043
 //   v2 = version_to_num([2,34,567]); // Returns: 2.340567
 //   v3 = version_to_num(2.120567);   // Returns: 2.120567
 //   v4 = version_to_num("2.6.79");   // Returns: 2.060079
-function version_to_num(x) =
+function version_to_num(version) =
-    let(x = version_to_list(x))
+    let(version = version_to_list(version))
-    (x[0]*1000000 + x[1]*10000 + x[2])/1000000;
+    (version[0]*1000000 + version[1]*10000 + version[2])/1000000;
 
 
 // Function: version_cmp()