Tweaks to edges.scad docs.

edges.scad

@@ -60,7 +60,6 @@ function _edges_text(edges) =
 
 
 // Section: Edge Constants
-//   Constants for working with edges.
 
 // Constant: EDGES_NONE
 // Topics: Edges
@@ -83,6 +82,7 @@ EDGES_ALL = [[1,1,1,1], [1,1,1,1], [1,1,1,1]];
 
 
 // Constant: EDGES_OFFSETS
+// Topics: Edges
 // See Also: EDGES_NONE, EDGES_ALL, edges()
 // Description:
 //   The vectors pointing to the center of each edge of a unit sized cube.
@@ -110,11 +110,15 @@ EDGE_OFFSETS = [
 // Section: Edge Helpers
 
 // Function: is_edge_array()
+// Topics: Edges, Type Checking
 // Usage:
-//   is_edge_array(v)
+//   bool = is_edge_array(x);
 // Description:
 //   Returns true if the given value has the form of an edge array.
-function is_edge_array(v) = is_list(v) && is_vector(v[0]) && len(v)==3 && len(v[0])==4;
+// Arguments:
+//   x = The item to check the type of.
+// See Also: edges(), EDGES_NONE, EDGES_ALL
+function is_edge_array(x) = is_list(x) && is_vector(x[0]) && len(x)==3 && len(x[0])==4;
 
 
 function _edge_set(v) =
@@ -150,18 +154,22 @@ function _edge_set(v) =
 
 
 // Function: normalize_edges()
+// Topics: Edges
 // Usage:
-//   normalize_edges(v);
+//   edges = normalize_edges(v);
 // Description:
 //   Normalizes all values in an edge array to be `1`, if it was originally greater than `0`,
 //   or `0`, if it was originally less than or equal to `0`.
+// See Also: is_edge_array(), edges(), EDGES_NONE, EDGES_ALL
 function normalize_edges(v) = [for (ax=v) [for (edge=ax) edge>0? 1 : 0]];
 
 
 // Function: edges()
+// Topics: Edges
 // Usage:
-//   edges(v)
+//   edgs = edges(v);
-//   edges(v, except)
+//   edgs = edges(v, except);
+//
 // Description:
 //   Takes a list of edge set descriptors, and returns a normalized edges array
 //   that represents all those given edges.  If the `except` argument is given
@@ -251,6 +259,8 @@ function normalize_edges(v) = [for (ax=v) [for (edge=ax) edge>0? 1 : 0]];
 //   v = The edge set to include.
 //   except = The edge set to specifically exclude, even if they are in `v`.
 //
+// See Also: is_edge_array(), normalize_edges(), EDGES_NONE, EDGES_ALL
+//
 // Example(3D): Just the front-top edge
 //   edg = edges(FRONT+TOP);
 //   show_edges(edges=edg);
@@ -283,6 +293,7 @@ function edges(v, except=[]) =
 
 
 // Module: show_edges()
+// Topics: Edges, Debugging
 // Usage:
 //   show_edges(edges, <size=>, <text=>, <txtsize=>);
 // Description:
@@ -292,6 +303,7 @@ function edges(v, except=[]) =
 //   size = The scalar size of the cube.
 //   text = The text to show on the front of the cube.
 //   txtsize = The size of the text.
+// See Also: is_edge_array(), edges(), EDGES_NONE, EDGES_ALL
 // Example:
 //   show_edges(size=30, edges=["X","Y"]);
 module show_edges(edges="ALL", size=20, text, txtsize=3) {
@@ -319,28 +331,31 @@ module show_edges(edges="ALL", size=20, text, txtsize=3) {
 
 
 // Constant: CORNERS_NONE
-// See Also: CORNERS_ALL, corners()
+// Topics: Corners
 // Description:
 //   The set of no corners.
 // Figure(3D):
 //   show_corners(corners="NONE");
+// See Also: CORNERS_ALL, corners()
 CORNERS_NONE = [0,0,0,0,0,0,0,0];  // No corners.
 
 
 // Constant: CORNERS_ALL
-// See Also: CORNERS_NONE, corners()
+// Topics: Corners
 // Description:
 //   The set of all corners.
 // Figure(3D):
 //   show_corners(corners="ALL");
+// See Also: CORNERS_NONE, corners()
 CORNERS_ALL = [1,1,1,1,1,1,1,1];
 
 
 // Constant: CORNER_OFFSETS
-// See Also: CORNERS_NONE, CORNERS_ALL, corners()
+// Topics: Corners
 // Description:
 //   The vectors pointing to each corner of a unit sized cube.
 //   Each item in a corner array will have a corresponding vector in this array.
+// See Also: CORNERS_NONE, CORNERS_ALL, corners()
 CORNER_OFFSETS = [
     [-1,-1,-1], [ 1,-1,-1], [-1, 1,-1], [ 1, 1,-1],
     [-1,-1, 1], [ 1,-1, 1], [-1, 1, 1], [ 1, 1, 1]
@@ -351,19 +366,23 @@ CORNER_OFFSETS = [
 // Section: Corner Helpers
 
 // Function: is_corner_array()
+// Topics: Corners, Type Checking
 // Usage:
-//   is_corner_array(v)
+//   bool = is_corner_array(x)
 // Description:
 //   Returns true if the given value has the form of a corner array.
-function is_corner_array(v) = is_vector(v) && len(v)==8 && all([for (x=v) x==1||x==0]);
+// See Also: CORNERS_NONE, CORNERS_ALL, corners()
+function is_corner_array(x) = is_vector(x) && len(x)==8 && all([for (xx=x) xx==1||xx==0]);
 
 
 // Function: normalize_corners()
+// Topics: Corners
 // Usage:
-//   normalize_corners(v);
+//   corns = normalize_corners(v);
 // Description:
 //   Normalizes all values in a corner array to be `1`, if it was originally greater than `0`,
 //   or `0`, if it was originally less than or equal to `0`.
+// See Also: CORNERS_NONE, CORNERS_ALL, is_corner_array(), corners()
 function normalize_corners(v) = [for (x=v) x>0? 1 : 0];
 
 
@@ -387,9 +406,10 @@ function _corner_set(v) =
 
 
 // Function: corners()
+// Topics: Corners
 // Usage:
-//   corners(v)
+//   corns = corners(v);
-//   corners(v, except)
+//   corns = corners(v, except);
 // Description:
 //   Takes a list of corner set descriptors, and returns a normalized corners array
 //   that represents all those given corners.  If the `except` argument is given
@@ -460,6 +480,7 @@ function _corner_set(v) =
 //       show_corners(corners="ALL");
 //       show_corners(corners="NONE");
 //   }
+// See Also: CORNERS_NONE, CORNERS_ALL, is_corner_array(), normalize_corners()
 // Example(3D): Just the front-top-right corner
 //   crn = corners(FRONT+TOP+RIGHT);
 //   show_corners(corners=crn);
@@ -486,22 +507,26 @@ function corners(v, except=[]) =
 
 
 // Function: corner_edges()
+// Topics: Corners
 // Description:
 //   Returns [XCOUNT,YCOUNT,ZCOUNT] where each is the count of edges aligned with that
 //   axis that are in the edge set and touch the given corner.
 // Arguments:
 //   edges = Standard edges array.
 //   v = Vector pointing to the corner to count edge intersections at.
+// See Also: CORNERS_NONE, CORNERS_ALL, is_corner_array(), corners(), corner_edge_count()
 function corner_edges(edges, v) =
     let(u = (v+[1,1,1])/2) [edges[0][u.y+u.z*2], edges[1][u.x+u.z*2], edges[2][u.x+u.y*2]];
 
 
 // Function: corner_edge_count()
+// Topics: Corners
 // Description:
 //   Counts how many given edges intersect at a specific corner.
 // Arguments:
 //   edges = Standard edges array.
 //   v = Vector pointing to the corner to count edge intersections at.
+// See Also: CORNERS_NONE, CORNERS_ALL, is_corner_array(), corners(), corner_edges()
 function corner_edge_count(edges, v) =
     let(u = (v+[1,1,1])/2) edges[0][u.y+u.z*2] + edges[1][u.x+u.z*2] + edges[2][u.x+u.y*2];
 
@@ -528,6 +553,7 @@ function _corners_text(corners) =
 
 
 // Module: show_corners()
+// Topics: Corners, Debugging
 // Usage:
 //   show_corners(corners, <size=>, <text=>, <txtsize=>);
 // Description:
@@ -537,6 +563,7 @@ function _corners_text(corners) =
 //   size = The scalar size of the cube.
 //   text = If given, overrides the text to be shown on the front of the cube.
 //   txtsize = The size of the text.
+// See Also: CORNERS_NONE, CORNERS_ALL, is_corner_array(), corners()
 // Example:
 //   show_corners(corners=FWD+RIGHT, size=30);
 module show_corners(corners="ALL", size=20, text, txtsize=3) {