Synopses, etc for bottlecaps.scad, comparisons.scad, constants.scad

bottlecaps.scad

@@ -17,6 +17,9 @@ include <rounding.scad>
 
 
 // Module: pco1810_neck()
+// Synopsis: Creates a neck for a PCO1810 standard bottle.
+// Topics: Bottles, Threading
+// See Also: pco1810_cap()
 // Usage:
 //   pco1810_neck([wall]) [ATTACHMENTS];
 // Description:
@@ -138,6 +141,9 @@ function  pco1810_neck(wall=2, anchor="support-ring", spin=0, orient=UP) =
 
 
 // Module: pco1810_cap()
+// Synopsis: Creates a cap for a PCO1810 standard bottle.
+// Topics: Bottles, Threading
+// See Also: pco1810_neck()
 // Usage:
 //   pco1810_cap([wall], [texture]) [ATTACHMENTS];
 // Description:
@@ -205,6 +211,9 @@ function pco1810_cap(wall=2, texture="none", anchor=BOTTOM, spin=0, orient=UP) =
 
 
 // Module: pco1881_neck()
+// Synopsis: Creates a neck for a PCO1881 standard bottle.
+// Topics: Bottles, Threading
+// See Also: pco1881_cap()
 // Usage:
 //   pco1881_neck([wall]) [ATTACHMENTS];
 // Description:
@@ -326,6 +335,9 @@ function pco1881_neck(wall=2, anchor="support-ring", spin=0, orient=UP) =
 
 
 // Module: pco1881_cap()
+// Synopsis: Creates a cap for a PCO1881 standard bottle.
+// Topics: Bottles, Threading
+// See Also: pco1881_neck()
 // Usage:
 //   pco1881_cap(wall, [texture]) [ATTACHMENTS];
 // Description:
@@ -385,6 +397,9 @@ function pco1881_cap(wall=2, texture="none", anchor=BOTTOM, spin=0, orient=UP) =
 // Section: Generic Bottle Connectors
 
 // Module: generic_bottle_neck()
+// Synopsis: Creates a generic neck for a bottle.
+// Topics: Bottles, Threading
+// See Also: generic_bottle_cap()
 // Usage:
 //   generic_bottle_neck([wall], ...) [ATTACHMENTS];
 // Description:
@@ -510,6 +525,9 @@ function generic_bottle_neck(
 
 
 // Module: generic_bottle_cap()
+// Synopsis: Creates a generic cap for a bottle.
+// Topics: Bottles, Threading
+// See Also: generic_bottle_neck()
 // Usage:
 //   generic_bottle_cap(wall, [texture], ...) [ATTACHMENTS];
 // Description:
@@ -596,6 +614,9 @@ function generic_bottle_cap(
 
 
 // Module: bottle_adapter_neck_to_cap()
+// Synopsis: Creates a generic adaptor between a neck and a cap.
+// Topics: Bottles, Threading
+// See Also: bottle_adaptor_neck_to_neck()
 // Usage:
 //   bottle_adapter_neck_to_cap(wall, [texture], ...) [ATTACHMENTS];
 // Description:
@@ -709,6 +730,9 @@ function bottle_adapter_neck_to_cap(
 
 
 // Module: bottle_adapter_cap_to_cap()
+// Synopsis: Creates a generic adaptor between a cap and a cap.
+// Topics: Bottles, Threading
+// See Also: bottle_adaptor_neck_to_cap(), bottle_adaptor_neck_to_neck()
 // Usage:
 //   bottle_adapter_cap_to_cap(wall, [texture]);
 // Description:
@@ -822,6 +846,9 @@ function bottle_adapter_cap_to_cap(
 
 
 // Module: bottle_adapter_neck_to_neck()
+// Synopsis: Creates a generic adaptor between a neck and a neck.
+// Topics: Bottles, Threading
+// See Also: bottle_adaptor_neck_to_cap(), bottle_adaptor_cap_to_cap()
 // Usage:
 //   bottle_adapter_neck_to_neck(...);
 // Description:
@@ -946,6 +973,9 @@ function bottle_adapter_neck_to_neck(
 
 
 // Module: sp_neck()
+// Synopsis: Creates an SPI threaded bottle neck.
+// Topics: Bottles, Threading
+// See Also: sp_cap()
 // Usage:
 //   sp_neck(diam, type, wall|id=, [style=], [bead=]) [ATTACHMENTS];
 // Description:
@@ -1143,6 +1173,9 @@ module sp_neck(diam,type,wall,id,style="L",bead=false, anchor, spin, orient)
 
 
 // Module: sp_cap()
+// Synopsis: Creates an SPI threaded bottle cap.
+// Topics: Bottles, Threading
+// See Also: sp_neck()
 // Usage:
 //   sp_cap(diam, type, wall, [style=], [top_adj=], [bot_adj=], [texture=], [$slop]) [ATTACHMENTS];
 // Description:
@@ -1233,6 +1266,9 @@ module sp_cap(diam,type,wall,style="L",top_adj=0, bot_adj=0, texture="none", anc
 
 
 // Function: sp_diameter()
+// Synopsis: Returns the base diameter of an SPI bottle neck from the nominal diameter and type number.
+// Topics: Bottles, Threading
+// See Also: sp_neck(), sp_cap()
 // Usage:
 //   true_diam = sp_diameter(diam,type)
 // Description:

comparisons.scad

@@ -12,6 +12,9 @@
 // Section: List comparison operations
 
 // Function: approx()
+// Synopsis: Returns true if two values are equal to within a small epsilon value.
+// Topics: Comparisons
+// See Also: all_zero(), all_nonzero()
 // Usage:
 //   test = approx(a, b, [eps])
 // Description:
@@ -44,6 +47,9 @@ function approx(a,b,eps=EPSILON) =
 
 
 // Function: all_zero()
+// Synopsis: Returns true if the value(s) given are aproximately zero.
+// Topics: Comparisons, List Handling
+// See Also: approx(), all_zero(), all_nonzero()
 // Usage:
 //   x = all_zero(x, [eps]);
 // Description:
@@ -64,6 +70,9 @@ function all_zero(x, eps=EPSILON) =
 
 
 // Function: all_nonzero()
+// Synopsis: Returns true if the value(s) given are not aproximately zero.
+// Topics: Comparisons, List Handling
+// See Also: approx(), all_zero(), all_nonzero()
 // Usage:
 //   test = all_nonzero(x, [eps]);
 // Description:
@@ -85,6 +94,9 @@ function all_nonzero(x, eps=EPSILON) =
 
 
 // Function: all_positive()
+// Synopsis: Returns true if the value(s) given are greater than zero.
+// Topics: Comparisons, List Handling
+// See Also: approx(), all_zero(), all_nonzero(), all_negative(), all_nonpositive(), all_nonnegative()
 // Usage:
 //   test = all_positive(x,[eps]);
 // Description:
@@ -108,6 +120,9 @@ function all_positive(x,eps=0) =
 
 
 // Function: all_negative()
+// Synopsis: Returns true if the value(s) given are less than zero.
+// Topics: Comparisons, List Handling
+// See Also: approx(), all_zero(), all_nonzero(), all_positive(), all_nonpositive(), all_nonnegative()
 // Usage:
 //   test = all_negative(x, [eps]);
 // Description:
@@ -132,6 +147,9 @@ function all_negative(x, eps=0) =
 
 
 // Function: all_nonpositive()
+// Synopsis: Returns true if the value(s) given are less than or equal to zero.
+// Topics: Comparisons, List Handling
+// See Also: approx(), all_zero(), all_nonzero(), all_positive(), all_negative(), all_nonpositive(), all_nonnegative()
 // Usage:
 //   all_nonpositive(x, [eps]);
 // Description:
@@ -156,6 +174,9 @@ function all_nonpositive(x,eps=0) =
 
 
 // Function: all_nonnegative()
+// Synopsis: Returns true if the value(s) given are greater than or equal to zero.
+// Topics: Comparisons, List Handling
+// See Also: approx(), all_zero(), all_nonzero(), all_positive(), all_negative(), all_nonpositive(), all_nonnegative()
 // Usage:
 //   all_nonnegative(x, [eps]);
 // Description:
@@ -181,6 +202,9 @@ function all_nonnegative(x,eps=0) =
 
 
 // Function: all_equal()
+// Synopsis: Returns true if all items in a list are approximately equal to each other.
+// Topics: Comparisons, List Handling
+// See Also: approx(), all_zero(), all_nonzero(), all_positive(), all_negative(), all_nonpositive(), all_nonnegative()
 // Usage:
 //   b = all_equal(vec, [eps]);
 // Description:
@@ -195,6 +219,9 @@ function all_equal(vec,eps=0) =
 
 
 // Function: are_ends_equal()
+// Synopsis: Returns true if the first and last items in a list are approximately equal.
+// Topics: Comparisons, List Handling
+// See Also: approx(), all_zero(), all_nonzero(), all_positive(), all_negative(), all_nonpositive(), all_nonnegative()
 // Usage:
 //   are_ends_equal(list, [eps]);
 // Description:
@@ -208,10 +235,11 @@ function are_ends_equal(list, eps=EPSILON) =
 
 
 // Function: is_increasing()
+// Synopsis: Returns true if exery item in a list is greater than the previous item. 
+// Topics: Comparisons, List Handling
+// See Also: max_index(), min_index(), is_increasing(), is_decreasing()
 // Usage:
 //    bool = is_increasing(list, [strict]);
-// Topics: List Handling
-// See Also: max_index(), min_index(), is_decreasing()
 // Description:
 //   Returns true if the list is (non-strictly) increasing, or strictly increasing if strict is set to true.
 //   The list can be a list of any items that OpenSCAD can compare, or it can be a string which will be
@@ -232,10 +260,11 @@ function is_increasing(list,strict=false) =
 
 
 // Function: is_decreasing()
+// Synopsis: Returns true if exery item in a list is less than the previous item. 
+// Topics: Comparisons, List Handling
+// See Also: max_index(), min_index(), is_increasing(), is_decreasing()
 // Usage:
 //   bool = is_decreasing(list, [strict]);
-// Topics: List Handling
-// See Also: max_index(), min_index(), is_increasing()
 // Description:
 //   Returns true if the list is (non-strictly) decreasing, or strictly decreasing if strict is set to true.
 //   The list can be a list of any items that OpenSCAD can compare, or it can be a string which will be
@@ -265,6 +294,9 @@ function _type_num(x) =
 
 
 // Function: compare_vals()
+// Synopsis: Compares two values, possibly of different type.
+// Topics: Comparisons, List Handling
+// See Also: approx(), is_increasing(), is_decreasing()
 // Usage:
 //   test = compare_vals(a, b);
 // Description:
@@ -283,6 +315,9 @@ function compare_vals(a, b) =
 
 
 // Function: compare_lists()
+// Synopsis: Compares two lists of values, possibly of different type.
+// Topics: Comparisons, List Handling
+// See Also: compare_vals(), approx(), is_increasing(), is_decreasing()
 // Usage:
 //   test = compare_lists(a, b)
 // Description:
@@ -310,11 +345,12 @@ function compare_lists(a, b) =
 
 
 // Function: min_index()
+// Synopsis: Returns the index of the minimal value in the given list.
+// Topics: List Handling
+// See Also: max_index(), is_increasing(), is_decreasing()
 // Usage:
 //   idx = min_index(vals);
 //   idxlist = min_index(vals, all=true);
-// Topics: List Handling
-// See Also: max_index(), is_increasing(), is_decreasing()
 // Description:
 //   Returns the index of the first occurrence of the minimum value in the given list. 
 //   If `all` is true then returns a list of all indices where the minimum value occurs.
@@ -330,11 +366,12 @@ function min_index(vals, all=false) =
 
 
 // Function: max_index()
+// Synopsis: Returns the index of the minimal value in the given list.
+// Topics: List Handling
+// See Also: min_index(), is_increasing(), is_decreasing()
 // Usage:
 //   idx = max_index(vals);
 //   idxlist = max_index(vals, all=true);
-// Topics: List Handling
-// See Also: min_index(), is_increasing(), is_decreasing()
 // Description:
 //   Returns the index of the first occurrence of the maximum value in the given list. 
 //   If `all` is true then returns a list of all indices where the maximum value occurs.
@@ -353,6 +390,7 @@ function max_index(vals, all=false) =
 
 
 // Function: find_approx()
+// Synopsis: Finds the indexes of the item(s) in the given list that are aproximately the given value.
 // Topics: List Handling
 // See Also: in_list()
 // Usage:
@@ -386,10 +424,11 @@ function __find_approx(val, list, eps, i=0) =
 
 
 // Function: deduplicate()
-// Usage:
+// Synopsis: Returns a list with all consecutive duplicate values removed.
-//   list = deduplicate(list, [closed], [eps]);
 // Topics: List Handling
 // See Also: deduplicate_indexed()
+// Usage:
+//   list = deduplicate(list, [closed], [eps]);
 // Description:
 //   Removes consecutive duplicate items in a list.
 //   When `eps` is zero, the comparison between consecutive items is exact.
@@ -419,10 +458,11 @@ function deduplicate(list, closed=false, eps=EPSILON) =
 
 
 // Function: deduplicate_indexed()
-// Usage:
+// Synopsis: Takes a list of indices into a list of values, and returns a list of indices whose values are not consecutively the same.
-//   new_idxs = deduplicate_indexed(list, indices, [closed], [eps]);
 // Topics: List Handling
 // See Also: deduplicate()
+// Usage:
+//   new_idxs = deduplicate_indexed(list, indices, [closed], [eps]);
 // Description:
 //   Given a list, and a list of indices, removes consecutive indices corresponding to list values that are equal
 //   or approximately equal.  
@@ -465,6 +505,9 @@ function deduplicate_indexed(list, indices, closed=false, eps=EPSILON) =
 
 
 // Function: list_wrap()
+// Synopsis: Returns a list whose last value is the same as the first.
+// Topics: List Handling, Paths
+// See Also: list_unwrap(), deduplicate()
 // Usage:
 //   list_wrap(path, [eps]);
 // Description:
@@ -474,7 +517,6 @@ function deduplicate_indexed(list, indices, closed=false, eps=EPSILON) =
 // Arguments:
 //   list = list to unwrap
 //   eps = epsilon for comparison.  Default: EPSILON (1e-9)
-// See Also: list_unwrap(), deduplicate()
 
 function list_wrap(list, eps=EPSILON) =
     assert(is_list(list))
@@ -490,6 +532,9 @@ function close_path(list,eps=EPSILON) =
   list_wrap(list,eps);
 
 // Function: list_unwrap()
+// Synopsis: Removes the last item of a list if it's first and last values are equal.
+// Topics: List Handling, Paths
+// See Also: list_wrap(), deduplicate()
 // Usage:
 //   list_unwrap(list, [eps]);
 // Description:
@@ -506,10 +551,11 @@ function list_unwrap(list, eps=EPSILON) =
 
 
 // Function: unique()
-// Usage:
+// Synopsis: Returns a sorted list with all duplicates removed.
-//   ulist = unique(list);
 // Topics: List Handling
 // See Also: shuffle(), sort(), sortidx(), unique_count()
+// Usage:
+//   ulist = unique(list);
 // Description:
 //   Given a string or a list returns the sorted string or the sorted list with all repeated items removed.
 //   The sorting order of non homogeneous lists is the function `sort` order.
@@ -548,10 +594,11 @@ function _unique_sort(l) =
 
 
 // Function: unique_count()
-// Usage:
+// Synopsis: Returns a sorted list of unique items with counts.
-//   sorted_counts = unique_count(list);
 // Topics: List Handling
 // See Also: shuffle(), sort(), sortidx(), unique()
+// Usage:
+//   sorted_counts = unique_count(list);
 // Description:
 //   Returns `[sorted,counts]` where `sorted` is a sorted list of the unique items in `list` and `counts` is a list such 
 //   that `count[i]` gives the number of times that `sorted[i]` appears in `list`.  
@@ -710,10 +757,11 @@ function _indexed_sort(arrind) =
 
 
 // Function: sort()
-// Usage:
+// Synopsis: Returns a sorted list.
-//   slist = sort(list, [idx]);
 // Topics: List Handling
 // See Also: shuffle(), sortidx(), unique(), unique_count(), group_sort()
+// Usage:
+//   slist = sort(list, [idx]);
 // Description:
 //   Sorts the given list in lexicographic order. The sort is stable, meaning equivalent items will not change order. 
 //   If the input is a homogeneous simple list or a homogeneous 
@@ -752,10 +800,11 @@ function sort(list, idx=undef) =
         
 
 // Function: sortidx()
-// Usage:
+// Synopsis: Returns a list of sorted indices into a list.
-//   idxlist = sortidx(list, [idx]);
 // Topics: List Handling
 // See Also: shuffle(), sort(), group_sort(), unique(), unique_count()
+// Usage:
+//   idxlist = sortidx(list, [idx]);
 // Description:
 //   Given a list, sort it as function `sort()`, and returns
 //   a list of indexes into the original list in that sorted order.
@@ -806,10 +855,11 @@ function sortidx(list, idx=undef) =
 
 
 // Function: group_sort()
+// Synopsis: Returns a sorted list of groups of values.
+// Topics: List Handling
+// See Also: group_data(), shuffle(), sort(), sortidx(), unique(), unique_count()
 // Usage:
 //   ulist = group_sort(list,[idx]);
-// Topics: List Handling
-// See Also: shuffle(), sort(), sortidx(), unique(), unique_count()
 // Description:
 //   Given a list of numbers, sorts the list into a sequence of lists, where each list contains any repeated values.
 //   If there are no repeated values the output will be a list of singleton lists.  
@@ -839,9 +889,11 @@ function group_sort(list, idx) =
 
 
 // Function: group_data()
+// Synopsis: Groups list data by integer group numbers.
+// Topics: List Handling
+// See Also: group_sort(), shuffle(), sort(), sortidx(), unique(), unique_count()
 // Usage:
 //   groupings = group_data(groups, values);
-// Topics: List Handling
 // Description:
 //   Given a list of integer group numbers, and an equal-length list of values,
 //   returns a list of groups with the values sorted into the corresponding groups.
@@ -877,6 +929,9 @@ function group_data(groups, values) =
 
 
 // Function: list_smallest()
+// Synopsis: Returns the `k` smallest values in the list, in arbitrary order.
+// Topics: List Handling
+// See Also: group_sort(), shuffle(), sort(), sortidx(), unique(), unique_count()
 // Usage:
 //   small = list_smallest(list, k)
 // Description:
@@ -900,4 +955,6 @@ function list_smallest(list, k) =
     let( bigger  = [for(li=list) if(li>v) li ] )
     concat(smaller, equal, list_smallest(bigger, k-len(smaller) -len(equal)));
 
+
+
 // vim: expandtab tabstop=4 shiftwidth=4 softtabstop=4 nowrap

constants.scad

@@ -15,6 +15,8 @@ _UNDEF="LRG+HX7dy89RyHvDlAKvb9Y04OTuaikpx205CTh8BSI";
 // Section: General Constants
 
 // Constant: $slop
+// Synopsis: The slop amount to make printed items fit closely.
+// Topics: Constants
 // Description:
 //   A number of printers, particularly FDM/FFF printers, tend to be a bit sloppy in their printing.
 //   This has made it so that some parts won't fit together without adding a bit of extra slop space.
@@ -102,6 +104,9 @@ _UNDEF="LRG+HX7dy89RyHvDlAKvb9Y04OTuaikpx205CTh8BSI";
 //   }
 
 // Function: get_slop()
+// Synopsis: Returns the $slop value.
+// Topics: Slop
+// See Also: $slop
 // Usage:
 //    slop = get_slop();
 // Description:
@@ -111,6 +116,8 @@ function get_slop() = is_undef($slop) ? 0 : $slop;
 
 
 // Constant: INCH
+// Synopsis: A constant containing the  number of millimeters in an inch.
+// Topics: Constants
 // Description:
 //   The number of millimeters in an inch.
 // Example(2D):
@@ -125,6 +132,7 @@ INCH = 25.4;
 //   Vectors useful for `rotate()`, `mirror()`, and `anchor` arguments for `cuboid()`, `cyl()`, etc.
 
 // Constant: LEFT
+// Synopsis: The left-wards (X-) direction vector constant `[-1,0,0]`.
 // Topics: Constants, Vectors
 // See Also: RIGHT, FRONT, BACK, UP, DOWN, CENTER
 // Description: Vector pointing left.  [-1,0,0]
@@ -133,6 +141,7 @@ INCH = 25.4;
 LEFT  = [-1,  0,  0];
 
 // Constant: RIGHT
+// Synopsis: The right-wards (X+) direction vector constant `[1,0,0]`.
 // Topics: Constants, Vectors
 // See Also: LEFT, FRONT, BACK, UP, DOWN, CENTER
 // Description: Vector pointing right.  [1,0,0]
@@ -142,6 +151,7 @@ RIGHT = [ 1,  0,  0];
 
 // Constant: FRONT
 // Aliases: FWD, FORWARD
+// Synopsis: The front-wards (Y-) direction vector constant `[0,-1,0]`.
 // Topics: Constants, Vectors
 // See Also: LEFT, RIGHT, BACK, UP, DOWN, CENTER
 // Description: Vector pointing forward.  [0,-1,0]
@@ -152,6 +162,7 @@ FWD = FRONT;
 FORWARD = FRONT;
 
 // Constant: BACK
+// Synopsis: The back-wards (Y+) direction vector constant `[0,1,0]`.
 // Topics: Constants, Vectors
 // See Also: LEFT, RIGHT, FRONT, UP, DOWN, CENTER
 // Description: Vector pointing back.  [0,1,0]
@@ -161,6 +172,7 @@ BACK  = [ 0,  1,  0];
 
 // Constant: BOTTOM
 // Aliases: BOT, DOWN
+// Synopsis: The down-wards (Z-) direction vector constant `[0,0,-1]`.
 // Topics: Constants, Vectors
 // See Also: LEFT, RIGHT, FRONT, BACK, UP, CENTER
 // Description: Vector pointing down.  [0,0,-1]
@@ -172,6 +184,7 @@ DOWN = BOTTOM;
 
 // Constant: TOP
 // Aliases: UP
+// Synopsis: The top-wards (Z+) direction vector constant `[0,0,1]`.
 // Topics: Constants, Vectors
 // See Also: LEFT, RIGHT, FRONT, BACK, DOWN, CENTER
 // Description: Vector pointing up.  [0,0,1]
@@ -182,6 +195,7 @@ UP = TOP;
 
 // Constant: CENTER
 // Aliases: CTR, CENTRE
+// Synopsis: The center vector constant `[0,0,0]`.
 // Topics: Constants, Vectors
 // See Also: LEFT, RIGHT, FRONT, BACK, UP, DOWN
 // Description: Zero vector.  Centered.  [0,0,0]
@@ -198,6 +212,7 @@ CENTRE = CENTER;
 //   with two endpoints.  
 
 // Constant: SEGMENT
+// Synopsis: A constant for specifying a line segment.
 // Topics: Constants, Lines
 // See Also: RAY, LINE
 // Description: Treat a line as a segment.  [true, true]
@@ -209,6 +224,7 @@ SEGMENT = [true,true];
 
 
 // Constant: RAY
+// Synopsis: A constant for specifying a ray line.
 // Topics: Constants, Lines
 // See Also: SEGMENT, LINE
 // Description: Treat a line as a ray, based at the first point.  [true, false]
@@ -220,6 +236,7 @@ RAY = [true, false];
 
 
 // Constant: LINE
+// Synopsis: A constant for specifying an unbounded line.
 // Topics: Constants, Lines
 // See Also: RAY, SEGMENT
 // Description: Treat a line as an unbounded line.  [false, false]
@@ -231,6 +248,9 @@ LINE = [false, false];
 
 
 // Constant: IDENT
+// Synopsis: A constant containing the 3D identity transformation matrix.
+// Topics: Affine, Matrices, Transforms
+// See Also: ident()
 // Description: Identity transformation matrix for three-dimensional transforms.  Equal to `ident(4)`.  
 IDENT=ident(4);