docs(all): corrections and improvements to documentation and examples

* docs(all): small changes to main MD files * docs(all): updated API readme doc to align with main repo * docs(modeling): corrections and improvements to doc strings and examples
jscad · Dec 29, 2024 · 0cd6beb · 0cd6beb
1 parent 1519c7d
commit 0cd6beb
Show file tree

Hide file tree

Showing 20 changed files with 45 additions and 33 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,8 @@
 
 All notable changes to this project will be documented in this file.
 
+## CHANGE LOGS ARE NOW FOUND IN EACH PACKAGE
+
 ## 0.6.0 (2017-05-xx)
 total rework of application and library structure:
 - modular, smaller codebase (node.js modules) instead of monolithic files

diff --git a/LICENSE b/LICENSE
@@ -1,7 +1,7 @@
 
 The MIT License (MIT)
 
-Copyright (c) 2017-2021 JSCAD Organization
+Copyright (c) 2017-2024 JSCAD Organization
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

diff --git a/jsdoc/assets/README.md b/jsdoc/assets/README.md
@@ -16,10 +16,10 @@ Check out the Tutorials section for tips on getting started, and best practises.
 
 There are different 'flavors' of JSCAD that you can use based on your needs
 - For browser-based modelling (no install) simply go to [https://openjscad.xyz/](https://openjscad.xyz/)
+- For the command line interface, install as part of a project using NPM. See [JSCAD Command Line Interface](https://www.npmjs.com/package/@jscad/cli) at NPM
 - For other usage options, the first step is to visit [JSCAD on GitHub](https://github.com/jscad/OpenJSCAD.org/)
-  * Command line interface : can be found in ./packages/cli
-  * Desktop app : pre-pre-alpha work in progress can be found  at ./packages/desktop
-  * For custom mix and match of packages, all the packages are available [on NPM](https://www.npmjs.com/search?q=%40jscad) under the '@jscad' name
+  * Review the available [list of packages](https://github.com/jscad/OpenJSCAD.org/tree/master/packages) at GitHub
+  * Packages are also available [on NPM](https://www.npmjs.com/search?q=%40jscad) under the '@jscad' name
 
 ## Documentation
 
@@ -29,9 +29,14 @@ There are different 'flavors' of JSCAD that you can use based on your needs
 
 ## Community
 
+Discuss designs or issues
 * [JSCAD User Group](https://openjscad.xyz/forum.html)
+
+Or chat with other users
 * [Discord Community](https://openjscad.xyz/discord.html)
 
+HUGE THANKS and SHOUTOUT to [nodeBB](https://nodebb.org/) for hosting our (awesome) forum for free ! Thanks a lot !
+
 ## Contributing
 
 The various JSCAD packages and all source code are part of the JSCAD Organization, and maintained by a group of volunteers.
@@ -47,9 +52,23 @@ We welcome and encourage anyone to pitch in but please take a moment to read the
 
 * If you have a change or new feature in mind, please start a conversation with the [Core Developers](https://openjscad.xyz/forum.html) and start contributing changes.
 
-A BIG THANKS to all the people who have already contributed to the JSCAD project!
+A BIG THANKS to all the people who have already contributed changes to the JSCAD project!
 <a href="https://github.com/jscad/OpenJSCAD.org/graphs/contributors"><img src="https://opencollective.com/openjscad/contributors.svg?width=890" alt="Open Collective"></a>
 
+## Backers
+
+Thank you to all our backers! 🙏 [[Become a backer](https://opencollective.com/openjscad#backer)]
+
+<a href="https://opencollective.com/openjscad#backers" target="_blank"><img src="https://opencollective.com/openjscad/backers.svg?width=890"></a>
+
+## Sponsors
+
+This project has some awesome sponsors! [[Become a sponsor](https://opencollective.com/openjscad#sponsor)]
+Your logo will show up here with a link to your website.
+
+<a href="https://opencollective.com/openjscad#backers" target="_blank"><object type="image/svg+xml" data="https://opencollective.com/openjscad/tiers/sponsors.svg?avatarHeight=36&width=600"></object></a>
+
+
 ## License
 
 [The MIT License (MIT)](https://github.com/jscad/OpenJSCAD.org/blob/master/LICENSE)

diff --git a/packages/modeling/src/curves/index.js b/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')

diff --git a/packages/modeling/src/maths/index.js b/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'),

diff --git a/packages/modeling/src/operations/booleans/intersect.js b/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
  * +-------+

diff --git a/packages/modeling/src/operations/booleans/scission.js b/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

diff --git a/packages/modeling/src/operations/booleans/subtract.js b/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
  * +-------+            +-------+

diff --git a/packages/modeling/src/operations/booleans/union.js b/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
  * +-------+            +-------+

diff --git a/packages/modeling/src/operations/expansions/expand.js b/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)

diff --git a/packages/modeling/src/operations/extrusions/extrudeHelical.js b/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 = {

diff --git a/packages/modeling/src/operations/extrusions/index.js b/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'),

diff --git a/packages/modeling/src/operations/hulls/index.js b/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'),

diff --git a/packages/modeling/src/operations/modifiers/index.js b/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'),

diff --git a/packages/modeling/src/operations/modifiers/snap.js b/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

diff --git a/packages/modeling/src/primitives/arc.js b/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 = {

diff --git a/packages/modeling/src/primitives/polyhedron.js b/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 = {

diff --git a/packages/modeling/src/text/vectorChar.js b/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) => {

diff --git a/packages/modeling/src/text/vectorText.js b/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) => {

diff --git a/packages/modeling/src/utils/index.js b/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'),