docs(modeling): corrections and improvements to doc strings and examples

packages/modeling/src/curves/index.js

@@ -3,7 +3,6 @@
  * @module modeling/curves
  * @example
  * const { bezier } = require('@jscad/modeling').curves
-
  */
 module.exports = {
   bezier: require('./bezier')

packages/modeling/src/maths/index.js

@@ -4,8 +4,7 @@
  * @see Most computations are based upon the glMatrix library (glmatrix.net)
  * @module modeling/maths
  * @example
- * const { constants, line2, mat4, vec2, vec3 } = require('@jscad/modeling').maths
-
+ * const { constants, line2, line3, mat4, plane, utils, vec2, vec3, vec4 } = require('@jscad/modeling').maths
  */
 module.exports = {
   constants: require('./constants'),

packages/modeling/src/operations/booleans/intersect.js

@@ -17,7 +17,7 @@ const intersectGeom3 = require('./intersectGeom3')
  * @alias module:modeling/booleans.intersect
  *
  * @example
- * let myshape = intersect(cube({size: [5,5,5]}), cube({size: [5,5,5], center: [5,5,5]}))
+ * let myshape = intersect(cube({size: 5}), cube({size: 5, center: [3,3,3]}))
  *
  * @example
  * +-------+

packages/modeling/src/operations/booleans/scission.js

@@ -9,6 +9,8 @@ const scissionGeom3 = require('./scissionGeom3')
 /**
  * Scission (divide) the given geometry into the component pieces.
  *
+ * NOTE: Currently only 3D geometries are supported.
+ *
  * @param {...Object} objects - list of geometries
  * @returns {Array} list of pieces from each geometry
  * @alias module:modeling/booleans.scission

packages/modeling/src/operations/booleans/subtract.js

@@ -17,7 +17,7 @@ const subtractGeom3 = require('./subtractGeom3')
  * @alias module:modeling/booleans.subtract
  *
  * @example
- * let myshape = subtract(cuboid({size: [5,5,5]}), cuboid({size: [5,5,5], center: [5,5,5]}))
+ * let myshape = subtract(cuboid({size: 5}), cuboid({size: 5, center: [3,3,3]}))
  *
  * @example
  * +-------+            +-------+

packages/modeling/src/operations/booleans/union.js

@@ -16,7 +16,7 @@ const unionGeom3 = require('./unionGeom3')
  * @alias module:modeling/booleans.union
  *
  * @example
- * let myshape = union(cube({size: [5,5,5]}), cube({size: [5,5,5], center: [5,5,5]}))
+ * let myshape = union(cube({size: 5}), cube({size: 5, center: [3,3,3]}))
  *
  * @example
  * +-------+            +-------+

packages/modeling/src/operations/expansions/expand.js

@@ -24,7 +24,7 @@ const expandPath2 = require('./expandPath2')
  * @example
  * let newarc = expand({delta: 5, corners: 'edge'}, arc({}))
  * let newsquare = expand({delta: 5, corners: 'chamfer'}, square({size: 30}))
- * let newsphere = expand({delta: 2, corners: 'round'}, cuboid({size: [20, 25, 5]}))
+ * let newcuboid = expand({delta: 2, corners: 'round'}, cuboid({size: [20, 25, 5]}))
  */
 const expand = (options, ...objects) => {
   objects = flatten(objects)

packages/modeling/src/operations/extrusions/extrudeHelical.js

@@ -19,14 +19,8 @@ const geom2 = require('../../geometries/geom2')
  * @alias module:modeling/extrusions.extrudeHelical
  *
  * @example
- * const myshape = extrudeHelical(
- *  {
- *      angle: Math.PI * 4,
- *      pitch: 10,
- *      segmentsPerRotation: 64
- *  },
- *  circle({size: 3, center: [10, 0]})
- * )
+ * const myshape = circle({size: 3, center: [10, 0]}) // position for extrusion about Z
+ * const mycoil = extrudeHelical({angle: TAU*2, pitch: 10, segmentsPerRotation: 64}, myshape))
  */
 const extrudeHelical = (options, geometry) => {
   const defaults = {

packages/modeling/src/operations/extrusions/index.js

@@ -3,7 +3,7 @@
  * In all cases, the function returns the results, and never changes the original shapes.
  * @module modeling/extrusions
  * @example
- * const { extrudeLinear, extrudeRectangular, extrudeRotate } = require('@jscad/modeling').extrusions
+ * const { extrudeHelical, extrudeLinear, extrudeRectangular, extrudeRotate, project, slice } = require('@jscad/modeling').extrusions
  */
 module.exports = {
   extrudeFromSlices: require('./extrudeFromSlices'),

packages/modeling/src/operations/hulls/index.js

@@ -4,7 +4,7 @@
  * In all cases, the function returns the results, and never changes the original shapes.
  * @module modeling/hulls
  * @example
- * const { hull, hullChain } = require('@jscad/modeling').hulls
+ * const { hull, hullChain, hullPoints2, hullPoints3 } = require('@jscad/modeling').hulls
  */
 module.exports = {
   hull: require('./hull'),

packages/modeling/src/operations/modifiers/index.js

@@ -3,7 +3,7 @@
  * In all cases, these functions returns the results, and never changes the original geometry.
  * @module modeling/modifiers
  * @example
- * const { snap } = require('@jscad/modeling').modifiers
+ * const { generalize, snap, retessellate } = require('@jscad/modeling').modifiers
  */
 module.exports = {
   generalize: require('./generalize'),

packages/modeling/src/operations/modifiers/snap.js

@@ -35,7 +35,7 @@ const snapGeom3 = (geometry) => {
 }
 
 /**
- * Snap the given geometries to the overall precision (epsilon) of the geometry.
+ * Snap the given geometries to the precision (calculated epsilon) of the geometry.
  * @see measurements.measureEpsilon()
  * @param {...Object} geometries - the geometries to snap
  * @return {Object|Array} the snapped geometry, or a list of snapped geometries

packages/modeling/src/primitives/arc.js

@@ -17,6 +17,8 @@ const { isGT, isGTE, isNumberArray } = require('./commonChecks')
  * @param {Boolean} [options.makeTangent=false] - adds line segments at both ends of the arc to ensure that the gradients at the edges are tangent
  * @returns {path2} new 2D path
  * @alias module:modeling/primitives.arc
+ * @example
+ * let myshape = arc({ center: [-1, -1], radius: 2, endAngle: (TAU / 4)})
  */
 const arc = (options) => {
   const defaults = {

packages/modeling/src/primitives/polyhedron.js

@@ -5,6 +5,7 @@ const { isNumberArray } = require('./commonChecks')
 
 /**
  * Construct a polyhedron in three dimensional space from the given set of 3D points and faces.
+ *
  * The faces can define outward or inward facing polygons (orientation).
  * However, each face must define a counter clockwise rotation of points which follows the right hand rule.
  * @param {Object} options - options for construction
@@ -18,7 +19,7 @@ const { isNumberArray } = require('./commonChecks')
  * @example
  * let mypoints = [ [10, 10, 0], [10, -10, 0], [-10, -10, 0], [-10, 10, 0], [0, 0, 10] ]
  * let myfaces = [ [0, 1, 4], [1, 2, 4], [2, 3, 4], [3, 0, 4], [1, 0, 3], [2, 1, 3] ]
- * let myshape = polyhedron({points: mypoint, faces: myfaces, orientation: 'inward'})
+ * let myshape = polyhedron({points: mypoints, faces: myfaces, orientation: 'inward'})
  */
 const polyhedron = (options) => {
   const defaults = {

packages/modeling/src/text/vectorChar.js

@@ -22,11 +22,8 @@ const vectorParams = require('./vectorParams')
 *
 * @example
 * let vectorCharObject = vectorChar()
-* or
 * let vectorCharObject = vectorChar('A')
-* or
 * let vectorCharObject = vectorChar({ xOffset: 57 }, 'C')
-* or
 * let vectorCharObject = vectorChar({ xOffset: 78, input: '!' })
 */
 const vectorChar = (options, char) => {

packages/modeling/src/text/vectorText.js

@@ -35,11 +35,8 @@ const translateLine = (options, line) => {
  *
  * @example
  * let textSegments = vectorText()
- * or
  * let textSegments = vectorText('OpenJSCAD')
- * or
  * let textSegments = vectorText({ yOffset: -50 }, 'OpenJSCAD')
- * or
  * let textSegments = vectorText({ yOffset: -80, input: 'OpenJSCAD' })
  */
 const vectorText = (options, text) => {

packages/modeling/src/utils/index.js

@@ -1,8 +1,8 @@
 /**
- * Utility functions of various sorts.
+ * Utility functions of various sorts, including conversions from different angular measures.
  * @module modeling/utils
  * @example
- * const { flatten, insertSorted } = require('@jscad/modeling').utils
+ * const { areAllShapesTheSameType, degToRad, radiusToSegments, radToDeg } = require('@jscad/modeling').utils
  */
 module.exports = {
   areAllShapesTheSameType: require('./areAllShapesTheSameType'),