Merge pull request #787 from adrianVmariano/master

doc fixes

skin.scad

@@ -769,7 +769,6 @@ module spiral_sweep(poly, h, r, turns=1, higbee, center, r1, r2, d, d1, d2, higb
 //   to produce a valid model in cases like this.  You can debug models like this using the `profiles=true` option which will show all
 //   the cross sections in your polyhedron.  If any of them intersect, the polyhedron will be invalid.  
 // Figure(3D,Big,VPR=[47,0,325],VPD=23,VPT=[6.8,4,-3.8],NoScales): We have scaled the path to an ellipse and enlarged the triangle, and it is now sometimes bigger than the local radius of the path, leading to an invalid polyhedron.
-// .
 //   tri= scale([4.5,2.5],[[0, 0], [0, 1], [1, 0]]);
 //   path = xscale(1.5,arc(r=5,N=81,angle=[-70,70]));
 //   % path_sweep(tri,path);
@@ -793,11 +792,9 @@ module spiral_sweep(poly, h, r, turns=1, higbee, center, r1, r2, d, d1, d2, higb
 //   unexpectedly around its axis as it traverses the path.  The `method` parameter allows you to specify how the shapes
 //   are aligned, resulting in different twist in the resulting polyhedron.  You can choose from three different methods
 //   for selecting the rotation of your shape.  None of these methods will produce good, or even valid, results on all
-//   inputs, so it is important to select a suitable method.  You can also explicitly add (or remove) twist to the
+//   inputs, so it is important to select a suitable method.  
-//   model.  This twist adjustment is done uniformly in arc length by default, or you can set `twist_by_length=false` to
-//   distribute the twist uniformly over the path point list.
 //   .
-//   The method is set using the parameter with that name to one of the following:
+//   The three methods you can choose using the `method` parameter are:
 //   .
 //   The "incremental" method (the default) works by adjusting the shape at each step by the minimal rotation that makes the shape normal to the tangent
 //   at the next point.  This method is robust in that it always produces a valid result for well-behaved paths with sufficiently high
@@ -1391,6 +1388,12 @@ function _ofs_face_edge(face,firstlen,second=false) =
 //   orient = Vector to rotate top towards after spin  (module only)
 //   atype = Select "hull" or "intersect" anchor types.  Default: "hull"
 //   cp = Centerpoint for determining "intersect" anchors or centering the shape.  Determintes the base of the anchor vector.  Can be "centroid", "mean", "box" or a 3D point.  Default: "centroid"
+// Example(VPR=[45,0.74]): A bent object that also changes shape along its length.
+//   radius = 75;
+//   angle = 40;
+//   shape = circle(r=5,$fn=32);
+//   T = [for(i=[0:25]) xrot(-angle*i/25,cp=[0,radius,0])*scale([1+i/25, 2-i/25,1])];
+//   sweep(shape,T);
 // Example: This is the "sweep-drop" example from list-comprehension-demos.
 //   function drop(t) = 100 * 0.5 * (1 - cos(180 * t)) * sin(180 * t) + 1;
 //   function path(t) = [0, 0, 80 + 80 * cos(180 * t)];

vnf.scad

@@ -296,6 +296,21 @@ function vnf_tri_array(points, row_wrap=false, reverse=false) =
 //   All the points in the input VNFs will appear in the output, even if they are
 //   duplicates of each other.  It is valid to repeat points in a VNF, but if you
 //   with to remove the duplicates that will occur along joined edges, use {{vnf_merge_points()}}.
+//   .
+//   Note that this is a tool for manipulating polyhedron data.  It is for
+//   building up a full polyhedron from partial polyhedra.
+//   It is *not* a union operator for VNFs.  The VNFs to be joined must not intersect each other, 
+//   except at edges, or the result will be an invalid polyhedron.  Similarly the
+//   result must not have any other illegal polyhedron characteristics, such as creating
+//   more than two faces sharing the same edge.  
+//   If you want a valid result it is your responsibility to ensure that the polyhedron
+//   has no holes, no intersecting faces or edges, and obeys all the requirements
+//   that CGAL expects. 
+//   .
+//   For example, if you combine two pyramids to try to make an octahedron, the result will
+//   be invalid because of the two internal faces created by the pyramid bases.  A valid
+//   use would be to build a cube missing one face and a pyramid missing its base and
+//   then join them into a cube with a point.  
 // Arguments:
 //   vnfs = a list of the VNFs to joint into one VNF.
 function vnf_join(vnfs) =