From 11260e28446ce47b95bbc1917259e106a9d903e3 Mon Sep 17 00:00:00 2001 From: Revar Desmera Date: Fri, 31 Mar 2023 01:30:09 -0700 Subject: [PATCH] Synopses, etc for bottlecaps.scad, comparisons.scad, constants.scad --- bottlecaps.scad | 36 ++++++++++++++++ comparisons.scad | 105 ++++++++++++++++++++++++++++++++++++----------- constants.scad | 20 +++++++++ 3 files changed, 137 insertions(+), 24 deletions(-) diff --git a/bottlecaps.scad b/bottlecaps.scad index 4668e7e..66b2f3e 100644 --- a/bottlecaps.scad +++ b/bottlecaps.scad @@ -17,6 +17,9 @@ include // 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: diff --git a/comparisons.scad b/comparisons.scad index bd2906a..8ecc382 100644 --- a/comparisons.scad +++ b/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: -// list = deduplicate(list, [closed], [eps]); +// Synopsis: Returns a list with all consecutive duplicate values removed. // 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: -// new_idxs = deduplicate_indexed(list, indices, [closed], [eps]); +// Synopsis: Takes a list of indices into a list of values, and returns a list of indices whose values are not consecutively the same. // 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: -// ulist = unique(list); +// Synopsis: Returns a sorted list with all duplicates removed. // 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: -// sorted_counts = unique_count(list); +// Synopsis: Returns a sorted list of unique items with counts. // 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: -// slist = sort(list, [idx]); +// Synopsis: Returns a sorted list. // 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: -// idxlist = sortidx(list, [idx]); +// Synopsis: Returns a list of sorted indices into a list. // 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 diff --git a/constants.scad b/constants.scad index 191d0ac..b2559fd 100644 --- a/constants.scad +++ b/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);