From 119de92f6e0bc65aed80a7a70dd67db8f123b8da Mon Sep 17 00:00:00 2001
From: Revar Desmera <revarbat@gmail.com>
Date: Mon, 3 Apr 2023 20:11:36 -0700
Subject: [PATCH] Added Synopses, etc to hinges.scad and joiners.scad

---
 hinges.scad  | 50 +++++++++++++++++++++++++++++++++++++-------------
 joiners.scad | 37 +++++++++++++++++++++++++++----------
 2 files changed, 64 insertions(+), 23 deletions(-)

diff --git a/hinges.scad b/hinges.scad
index 8c6420e..27fc746 100644
--- a/hinges.scad
+++ b/hinges.scad
@@ -14,23 +14,32 @@ include <screws.scad>
 // Section: Hinges
 
 // Module: knuckle_hinge()
+// Synopsis: Creates a knuckle-hinge shape.
+// Topics: Hinges, Parts
+// See Also: living_hinge_mask(), snap_lock(), snap_socket()
 // Usage:
 //   knuckle_hinge(length, offset, segs, [inner], [arm_height=], [arm_angle=], [fill=], [clear_top=], [gap=], [round_top=], [round_bot=], [knuckle_diam=], [pin_diam=], [pin_fn=], [anchor=], [spin=], [orient=]) [ATTACHMENTS];
 // Description:
-//   Construct standard knuckle hinge in two parts using a hinge pin that must be separately supplied.  The default is configured to use a piece of 1.75 mm filament as the hinge pin,
-//   but you can select any dimensions you like to use a screw or other available pin material.  The BOTTOM of the hinge is its mount point, which is aligned with
-//   the hinge pin centersurface, and the hinge pin hole is the CENTER of the hinge.  
-//   The offset is the distance from a vertical mounting point to the center of the hinge pin.  The hinge barrel is held by an angled support and
-//   vertical support.  The length of the angled support is determined by its angle and the offset.  You specify the length of the vertical support with the
-//   arm_height parameter.
-//   
+//   Construct standard knuckle hinge in two parts using a hinge pin that must be separately supplied.
+//   The default is configured to use a piece of 1.75 mm filament as the hinge pin, but you can select
+//   any dimensions you like to use a screw or other available pin material.  The BOTTOM of the hinge
+//   is its mount point, which is aligned with the hinge pin centersurface, and the hinge pin hole is
+//   the CENTER of the hinge.  The offset is the distance from a vertical mounting point to the center
+//   of the hinge pin.  The hinge barrel is held by an angled support and vertical support.  The
+//   length of the angled support is determined by its angle and the offset.  You specify the length
+//   of the vertical support with the arm_height parameter.
 //   .
-//   A hinge requires clearance so its parts don't interfere.  If the hinge pin is exactly centered on the top of your part, then the hinge may not close all the way
-//   due to interference at the edge.  A small clearance, specified with `clearance=`, raises the hinge up and can ease this interference.  It should probably be equal to a layer thickness or two.
-//   If the hinge knuckle is close to the hinged part then the mating part may interfere.  You can create clearance to address this problem by increasing the offset
-//   to move the hinge knuckles farther away.  Another method is to cut out a curved recess on the parts to allow space for the other hinges.  This is possible
-//   using the `knuckle_clearance=` parameter, which specifies the extra space to cut away to leave room for the hinge knuckles.  It must be positive for any space
-//   to be cut, and to use this option you must make the hinge a child of some object and specify {{diff()}} for the parent object of the hinge. 
+//   A hinge requires clearance so its parts don't interfere.  If the hinge pin is exactly centered on
+//   the top of your part, then the hinge may not close all the way due to interference at the edge.
+//   A small clearance, specified with `clearance=`, raises the hinge up and can ease this
+//   interference.  It should probably be equal to a layer thickness or two.  If the hinge knuckle is
+//   close to the hinged part then the mating part may interfere.  You can create clearance to address
+//   this problem by increasing the offset to move the hinge knuckles farther away.  Another method is
+//   to cut out a curved recess on the parts to allow space for the other hinges.  This is possible
+//   using the `knuckle_clearance=` parameter, which specifies the extra space to cut away to leave
+//   room for the hinge knuckles.  It must be positive for any space to be cut, and to use this option
+//   you must make the hinge a child of some object and specify {{diff()}} for the parent object of
+//   the hinge.
 // Figure(2D,Med,NoScales):  The basic hinge form appears on the left.  If fill is set to true the gap between the mount surface and hinge arm is filled as shown on the right. 
 //   _knuckle_hinge_profile(4, 5, $fn=32, fill=false);
 //   right(13)_knuckle_hinge_profile(4, 5, $fn=32, fill=true);
@@ -336,6 +345,9 @@ module _knuckle_hinge_profile(offset, arm_height, arm_angle=45, knuckle_diam=4,
 
 
 // Module: living_hinge_mask()
+// Synopsis: Creates a mask to make a folding "living" hinge.
+// Topics: Hinges, Parts
+// See Also: knuckle_hinge(), living_hinge_mask(), snap_lock(), snap_socket(), apply_folding_hinges_and_snaps()
 // Usage:
 //   living_hinge_mask(l, thick, [layerheight=], [foldangle=], [hingegap=], [$slop=], [anchor=], [spin=], [orient=]) [ATTACHMENTS];
 // Description:
@@ -378,6 +390,9 @@ module folding_hinge_mask(l, thick, layerheight=0.2, foldangle=90, hingegap=unde
 
 
 // Module: apply_folding_hinges_and_snaps()
+// Synopsis: Adds snap shapes and removes living hinges from a child shape.
+// Topics: Hinges, Parts
+// See Also: knuckle_hinge(), living_hinge_mask(), snap_lock(), snap_socket()
 // Usage:
 //   apply_folding_hinges_and_snaps(thick, [foldangle=], [hinges=], [snaps=], [sockets=], [snaplen=], [snapdiam=], [hingegap=], [layerheight=], [$slop=]) CHILDREN;
 // Description:
@@ -460,6 +475,9 @@ module apply_folding_hinges_and_snaps(thick, foldangle=90, hinges=[], snaps=[],
 
 
 // Module: snap_lock()
+// Synopsis: Creates a snap-lock shape.
+// Topics: Hinges, Parts
+// See Also: knuckle_hinge(), living_hinge_mask(), snap_lock(), snap_socket()
 // Usage:
 //   snap_lock(thick, [snaplen=], [snapdiam=], [layerheight=], [foldangle=], [hingegap=], [$slop=], [anchor=], [spin=], [orient=]) [ATTACHMENTS];
 // Description:
@@ -496,6 +514,9 @@ module snap_lock(thick, snaplen=5, snapdiam=5, layerheight=0.2, foldangle=90, hi
 
 
 // Module: snap_socket()
+// Synopsis: Creates a snap-lock socket shape.
+// Topics: Hinges, Parts
+// See Also: knuckle_hinge(), living_hinge_mask(), snap_lock(), snap_socket()
 // Usage:
 //   snap_socket(thick, [snaplen=], [snapdiam=], [layerheight=], [foldangle=], [hingegap=], [$slop=], [anchor=], [spin=], [orient=]) [ATTACHMENTS];
 // Description:
@@ -533,3 +554,6 @@ module snap_socket(thick, snaplen=5, snapdiam=5, layerheight=0.2, foldangle=90,
     }
 }
 
+
+
+// vim: expandtab tabstop=4 shiftwidth=4 softtabstop=4 nowrap
diff --git a/joiners.scad b/joiners.scad
index 7cf7a98..bdf0a90 100644
--- a/joiners.scad
+++ b/joiners.scad
@@ -16,11 +16,13 @@ include <rounding.scad>
 
 
 // Function&Module: half_joiner_clear()
+// Synopsis: Creates a mask to clear space for a {{half_joiner()}}.
+// Topics: Joiners, Parts
+// See Also: half_joiner_clear(), half_joiner(), half_joiner2(), joiner_clear(), joiner(), snap_pin(), rabbit_clip(), dovetail()
 // Usage: As Module
 //   half_joiner_clear(l, w, [ang=], [clearance=], [overlap=]) [ATTACHMENTS];
 // Usage: As Function
 //   vnf = half_joiner_clear(l, w, [ang=], [clearance=], [overlap=]);
-// Topics: Joiners, Parts
 // Description:
 //   Creates a mask to clear an area so that a half_joiner can be placed there.
 // Arguments:
@@ -33,7 +35,6 @@ include <rounding.scad>
 //   anchor = Translate so anchor point is at origin (0,0,0).  See [anchor](attachments.scad#subsection-anchor).  Default: `CENTER`
 //   spin = Rotate this many degrees around the Z axis after anchor.  See [spin](attachments.scad#subsection-spin).  Default: `0`
 //   orient = Vector to rotate top towards, after spin.  See [orient](attachments.scad#subsection-orient).  Default: `UP`
-// See Also: half_joiner_clear(), half_joiner(), half_joiner2(), joiner_clear(), joiner()
 // Example:
 //   half_joiner_clear();
 function half_joiner_clear(l=20, w=10, ang=30, clearance=0, overlap=0.01, anchor=CENTER, spin=0, orient=UP) =
@@ -60,11 +61,13 @@ module half_joiner_clear(l=20, w=10, ang=30, clearance=0, overlap=0.01, anchor=C
 
 
 // Function&Module: half_joiner()
+// Synopsis: Creates a half-joiner shape to mate with a {{half_joiner2()}} shape..
+// Topics: Joiners, Parts
+// See Also: half_joiner_clear(), half_joiner(), half_joiner2(), joiner_clear(), joiner(), snap_pin(), rabbit_clip(), dovetail()
 // Usage: As Module
 //   half_joiner(l, w, [base=], [ang=], [screwsize=], [$slop=]) [ATTACHMENTS];
 // Usage: As Function
 //   vnf = half_joiner(l, w, [base=], [ang=], [screwsize=], [$slop=]);
-// Topics: Joiners, Parts
 // Description:
 //   Creates a half_joiner object that can be attached to a matching half_joiner2 object.
 // Arguments:
@@ -78,7 +81,6 @@ module half_joiner_clear(l=20, w=10, ang=30, clearance=0, overlap=0.01, anchor=C
 //   spin = Rotate this many degrees around the Z axis after anchor.  See [spin](attachments.scad#subsection-spin).  Default: `0`
 //   orient = Vector to rotate top towards, after spin.  See [orient](attachments.scad#subsection-orient).  Default: `UP`
 //   $slop = Printer specific slop value to make parts fit more closely.
-// See Also: half_joiner_clear(), half_joiner(), half_joiner2(), joiner_clear(), joiner()
 // Examples(FlatSpin,VPD=75):
 //   half_joiner(screwsize=3);
 //   half_joiner(l=20,w=10,base=10);
@@ -241,11 +243,13 @@ module half_joiner(l=20, w=10, base=10, ang=30, screwsize, anchor=CENTER, spin=0
 
 
 // Function&Module: half_joiner2()
+// Synopsis: Creates a half_joiner2 shape to mate with a {{half_joiner()}} shape..
+// Topics: Joiners, Parts
+// See Also: half_joiner_clear(), half_joiner(), half_joiner2(), joiner_clear(), joiner(), snap_pin(), rabbit_clip(), dovetail()
 // Usage: As Module
 //   half_joiner2(l, w, [base=], [ang=], [screwsize=])
 // Usage: As Function
 //   vnf = half_joiner2(l, w, [base=], [ang=], [screwsize=])
-// Topics: Joiners, Parts
 // Description:
 //   Creates a half_joiner2 object that can be attached to half_joiner object.
 // Arguments:
@@ -258,7 +262,6 @@ module half_joiner(l=20, w=10, base=10, ang=30, screwsize, anchor=CENTER, spin=0
 //   anchor = Translate so anchor point is at origin (0,0,0).  See [anchor](attachments.scad#subsection-anchor).  Default: `CENTER`
 //   spin = Rotate this many degrees around the Z axis after anchor.  See [spin](attachments.scad#subsection-spin).  Default: `0`
 //   orient = Vector to rotate top towards, after spin.  See [orient](attachments.scad#subsection-orient).  Default: `UP`
-// See Also: half_joiner_clear(), half_joiner(), half_joiner2(), joiner_clear(), joiner()
 // Examples(FlatSpin,VPD=75):
 //   half_joiner2(screwsize=3);
 //   half_joiner2(w=10,base=10,l=20);
@@ -444,11 +447,13 @@ module half_joiner2(l=20, w=10, base=10, ang=30, screwsize, anchor=CENTER, spin=
 
 
 // Module: joiner_clear()
+// Synopsis: Creates a mask to clear space for a {{joiner()}} shape.
+// Topics: Joiners, Parts
+// See Also: half_joiner_clear(), half_joiner(), half_joiner2(), joiner_clear(), joiner(), snap_pin(), rabbit_clip(), dovetail()
 // Description:
 //   Creates a mask to clear an area so that a joiner can be placed there.
 // Usage:
 //   joiner_clear(l, w, [ang=], [clearance=], [overlap=]) [ATTACHMENTS];
-// Topics: Joiners, Parts
 // Arguments:
 //   l = Length of the joiner to clear space for.
 //   w = Width of the joiner to clear space for.
@@ -459,7 +464,6 @@ module half_joiner2(l=20, w=10, base=10, ang=30, screwsize, anchor=CENTER, spin=
 //   anchor = Translate so anchor point is at origin (0,0,0).  See [anchor](attachments.scad#subsection-anchor).  Default: `CENTER`
 //   spin = Rotate this many degrees around the Z axis after anchor.  See [spin](attachments.scad#subsection-spin).  Default: `0`
 //   orient = Vector to rotate top towards, after spin.  See [orient](attachments.scad#subsection-orient).  Default: `UP`
-// See Also: half_joiner_clear(), half_joiner(), half_joiner2(), joiner_clear(), joiner()
 // Example:
 //   joiner_clear();
 function joiner_clear(l=40, w=10, ang=30, clearance=0, overlap=0.01, anchor=CENTER, spin=0, orient=UP) = no_function("joiner_clear");
@@ -482,9 +486,11 @@ module joiner_clear(l=40, w=10, ang=30, clearance=0, overlap=0.01, anchor=CENTER
 
 
 // Module: joiner()
+// Synopsis: Creates a joiner shape that can mate with another rotated joiner shape.
+// Topics: Joiners, Parts
+// See Also: half_joiner_clear(), half_joiner(), half_joiner2(), joiner_clear(), joiner(), snap_pin(), rabbit_clip(), dovetail()
 // Usage:
 //   joiner(l, w, base, [ang=], [screwsize=], [$slop=]) [ATTACHMENTS];
-// Topics: Joiners, Parts
 // Description:
 //   Creates a joiner object that can be attached to another joiner object.
 // Arguments:
@@ -498,7 +504,6 @@ module joiner_clear(l=40, w=10, ang=30, clearance=0, overlap=0.01, anchor=CENTER
 //   spin = Rotate this many degrees around the Z axis after anchor.  See [spin](attachments.scad#subsection-spin).  Default: `0`
 //   orient = Vector to rotate top towards, after spin.  See [orient](attachments.scad#subsection-orient).  Default: `UP`
 //   $slop = Printer specific slop value to make parts fit more closely.
-// See Also: half_joiner_clear(), half_joiner(), half_joiner2(), joiner_clear(), joiner()
 // Examples(FlatSpin,VPD=125):
 //   joiner(screwsize=3);
 //   joiner(l=40, w=10, base=10);
@@ -532,6 +537,9 @@ module joiner(l=40, w=10, base=10, ang=30, screwsize, anchor=CENTER, spin=0, ori
 // Section: Dovetails
 
 // Module: dovetail()
+// Synopsis: Creates a possibly tapered dovetail shape.
+// Topics: Joiners, Parts
+// See Also: joiner(), snap_pin(), rabbit_clip()
 //
 // Usage:
 //   dovetail(gender, w=|width, h=|height, slide|thickness=, [slope=|angle=], [taper=|back_width=], [chamfer=], [r=|radius=], [round=], [extra=], [$slop=])
@@ -799,6 +807,9 @@ function _pin_size(size) =
 
 
 // Module: snap_pin()
+// Synopsis: Creates a snap-pin that can slot into a {{snap_pin_socket()}} to join two parts.
+// Topics: Joiners, Parts
+// See Also: snap_pin_socket(), joiner(), dovetail(), snap_pin(), rabbit_clip()
 // Usage:
 //    snap_pin(size, [pointed=], [anchor=], [spin=], [orient]=) [ATTACHMENTS];
 //    snap_pin(r=|radius=|d=|diameter=, l=|length=, nub_depth=, snap=, thickness=, [clearance=], [preload=], [pointed=]) [ATTACHMENTS];
@@ -869,6 +880,9 @@ module snap_pin(size,r,radius,d,diameter, l,length, nub_depth, snap, thickness,
 }
 
 // Module: snap_pin_socket()
+// Synopsis: Creates a snap-pin socket for a {{snap_pin()}} to slot into.
+// Topics: Joiners, Parts
+// See Also: snap_pin(), joiner(), dovetail(), snap_pin(), rabbit_clip()
 // Usage:
 //   snap_pin_socket(size, [fixed=], [fins=], [pointed=], [anchor=], [spin=], [orient=]) [ATTACHMENTS];
 //   snap_pin_socket(r=|radius=|d=|diameter=, l=|length=, nub_depth=, snap=, [fixed=], [pointed=], [fins=]) [ATTACHMENTS];
@@ -939,6 +953,9 @@ module snap_pin_socket(size, r, radius, l,length, d,diameter,nub_depth, snap, fi
 
 
 // Module: rabbit_clip()
+// Synopsis: Creates a rabbit-eared clip that can snap into a slot.
+// Topics: Joiners, Parts
+// See Also: snap_pin(), joiner(), dovetail(), snap_pin(), rabbit_clip()
 // Usage:
 //   rabbit_clip(type, length, width, snap, thickness, depth, [compression=], [clearance=], [lock=], [lock_clearance=], [splineteps=], [anchor=], [orient=], [spin=]) [ATTACHMENTS];
 // Description: