Add documentation

c3cat-bottle-clip/c3cat-bottle-clip.scad

@@ -12,6 +12,10 @@
  * https://www.thingiverse.com/thing:5029374
  * printed at scale 0.2 as glue-ins for additional ears.
  *
+ * This file has also being modified and reformatted by Ajabep to:
+ * - be easier to understand
+ * - be easier to modify and extend
+ * - be easier to use and build
  *
  * The contents of this file are licenced under CC-BY-SA 3.0 Unported.
  * See https://creativecommons.org/licenses/by-sa/3.0/deed for the
@@ -75,6 +79,30 @@ scale([0.2, 0.2, 0.2]) {
     ears_style=EARS_STYLE);
 }
 
+/**
+ * Render a bottle clip with a name, logo and ears (depending the `ears_style` argument) for a bottle given as `format`.
+ *
+ * Parameters:
+ * name: The name to write on the clip
+ * font: The font file to use
+ * logo: The logo file to print on the clip
+ *
+ * format: id of the bottle clip format
+ *            0: Club Mate 50cL
+ *            1: Long Neck as 25cL Club Mate or Fritz-kola
+ *            2: Euroform 2
+ *            3: Steinie bottles (with logo and name)
+ *
+ * ear_style: id of the ear style we want:
+ *               -1 or less: Should NEVER being used. Unknown behavior.
+ *               0: No ears, just a bottle clip with a name and a logo.
+ *               1: Just arcs.
+ *               2: Filled ears with the same thickness
+ *               3: Filled ears with the a thinner thickness inside
+ *               4: Filled ears with the same thickness but shifted
+ *
+ * By default, thus function will generate a clip for a 50cL Club-Mate Bottle, with a headband with cat ears as a logo, and with a cat ears of the clip formed by 2 arcs.
+ */
 module render_bottle_clip(name="", font="", logo="", format=0, ears_style=1) {
   name = name == "" ? "c3cat" : name ;
   font = font == "" ? "write/orbitron.dxf" : font ;
@@ -182,6 +210,25 @@ module logo(logo, rl, ht, ru, width) {
   }
 }
 
+/**
+ * Creates a Bootle Clip with logo and/or text, depending what is asked using the RENDER_COLOR_* variables.
+ *
+ * Parameters:
+ *
+ * Size:
+ * ht: the height of the bottle clip
+ * ru: the radius on the upper side of the clip
+ * rl: the radius on the lower side of the clip
+ * width: the thickness of the bottle clip
+ *
+ * name: The name to write on the clip
+ * font: The font file to use
+ * logo: The logo file to print on the clip
+ *
+ * By default, will create a Club-Mate 0.5L bottle clip.
+ *
+ * An empty logo file will create a headband with cat ears as a logo.
+ */
 module bottle_clip(ru=13, rl=17.5, ht=26, width=2.5, name="c3cat", font="write/orbitron.dxf", logo="") {
   e = 100;  // should be big enough, used for the outer boundary of the text/logo
 
@@ -261,6 +308,12 @@ module outer_cutoff(rl, e, ru, ht, width) {
  * ear_chamfer_shape: The shape of the chamfer: "cone", "curve", "curve-in", "pyramid", maybe some others
  * ear_details: whether to chamfer also the partial arcs
  *
+ * ear_style: id of the ear style we want:
+ *               0 or less: Should NEVER being used. Unknown behavior.
+ *               1: Just arcs.
+ *               2: Filled ears with the same thickness
+ *               3: Filled ears with the a thinner thickness inside
+ *               4: Filled ears with the same thickness but shifted
  */
 module ears(ht, ru, rl, clip_width, space_between_ears = 15, ear_tilt = 15, ear_depth=2, ear_thickness=.6, ear_side_len=6, ear_bend_factor=0.5, ear_stretch_factor=1.2, ear_chamfer=1, ear_chamfer_shape="curve", ear_details=true, ears_style=1) {
 
@@ -459,6 +512,30 @@ module ears(ht, ru, rl, clip_width, space_between_ears = 15, ear_tilt = 15, ear_
           }
 }
 
+/**
+ * Module that creates an ear given a style id.
+ *
+ * Parameters:
+ *
+ * style: id of the ear style we want:
+ *           0 or less: Should NEVER being used. Unknown behavior.
+ *           1: Just arcs.
+ *           2: Filled ears with the same thickness
+ *           3: Filled ears with the a thinner thickness inside
+ *           4: Filled ears with the same thickness but shifted
+ *
+ * depth: the depth of the ear
+ * thickness: the thickness of the ear arcs
+ * side_len: the length of one side of the ear base triangle
+ * bend_factor: how much the ear is bent. 1 = half circle, 0.00001 = almost straight
+ * stretch_factor: how much the ear is stretched, useful for fox ears or this kind of shapes
+ *
+ * chamfer: size of the chamfer to apply to the edges
+ * chamfer_shape: The shape of the chamfer: "cone", "curve", "curve-in", "pyramid", maybe some others
+ * details: whether to chamfer also the partial arcs
+ *
+ * By default, this module creates a cat ear countour.
+ */
 module ear_with_style(style = 1, depth, thickness, side_len=30, bend_factor=0.5, stretch_factor=1.2, chamfer=1, chamfer_shape="curve", details=true) {
   if (style == 1 || style == 2 || style == 3 || style == 4) {
     // Style 1: Just arcs
@@ -528,7 +605,7 @@ module ear_with_style(style = 1, depth, thickness, side_len=30, bend_factor=0.5,
   * chamfer_shape: The shape of the chamfer: "cone", "curve", "curve-in", "pyramid", maybe some others
   * details: whether to chamfer also the partial arcs
   *
-  * By default, this module creates an ear.
+  * By default, this module creates a cat ear.
   *
   * I don't remember the original author of this module. I refactored it and improved it a bit. Documentation is from me.
   */
@@ -579,9 +656,10 @@ module ear(depth, thickness, side_len=30, bend_factor=0.5, stretch_factor=1.2, c
   // $hc is the height of $C.
   $hc=-$C.x;
 
-  // If I correctly understood, $alpha should be the angle of the $B$A$C. This should be 60deg... but is not. idk why.
+  // $alpha should be the angle of the $B$A$C. This should is 60deg if `stretch_factor` is `1`, but this angle change with this factor.
   $alpha=asin($hc/$b);
   $beta=$alpha;
+  // $gamma is the $A$C$B angle.
   $gamma=180-$alpha-$beta;
   $delta=180*bend_factor;
   $bend_radius=$a/(2*cos(90-$delta/2));