From 0cd6beb5540f4797b47d9354b9d469e0181ac371 Mon Sep 17 00:00:00 2001 From: Z3 Development Date: Sun, 29 Dec 2024 09:31:34 +0900 Subject: [PATCH] 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 --- CHANGELOG.md | 2 ++ LICENSE | 2 +- jsdoc/assets/README.md | 27 ++++++++++++++++--- packages/modeling/src/curves/index.js | 1 - packages/modeling/src/maths/index.js | 3 +-- .../src/operations/booleans/intersect.js | 2 +- .../src/operations/booleans/scission.js | 2 ++ .../src/operations/booleans/subtract.js | 2 +- .../modeling/src/operations/booleans/union.js | 2 +- .../src/operations/expansions/expand.js | 2 +- .../operations/extrusions/extrudeHelical.js | 10 ++----- .../src/operations/extrusions/index.js | 2 +- .../modeling/src/operations/hulls/index.js | 2 +- .../src/operations/modifiers/index.js | 2 +- .../modeling/src/operations/modifiers/snap.js | 2 +- packages/modeling/src/primitives/arc.js | 2 ++ .../modeling/src/primitives/polyhedron.js | 3 ++- packages/modeling/src/text/vectorChar.js | 3 --- packages/modeling/src/text/vectorText.js | 3 --- packages/modeling/src/utils/index.js | 4 +-- 20 files changed, 45 insertions(+), 33 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index fe3209840..39cde6639 100644 --- 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 index c4f41d3d4..3d2ab6c08 100644 --- 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 index 2b515fb94..ceef996c9 100644 --- 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! Open Collective +## Backers + +Thank you to all our backers! 🙏 [[Become a backer](https://opencollective.com/openjscad#backer)] + + + +## 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. + + + + ## 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 index b22d05388..64b698926 100644 --- 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 index b4b0ed078..98db789b8 100644 --- 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 index b90960415..4061c777c 100644 --- 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 index 54a609497..00bba34d2 100644 --- 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 index 8505deb62..6952a0137 100644 --- 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 index 78aaf3502..41d7de186 100644 --- 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 index b92d153d7..fbf587464 100644 --- 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 index c38bb1bf2..d0d59e601 100644 --- 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 index 22d330171..59797adf0 100644 --- 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 index f5570e087..650d65fa1 100644 --- 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 index d4e21cbb3..588d05436 100644 --- 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 index 93f76f044..8ba7089ef 100644 --- 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 index f5734bf13..02edca8b4 100644 --- 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 index 237128681..94d119fc1 100644 --- 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 index 5de715fba..a815eb804 100644 --- 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 index ef5de5e2c..3cc926ce3 100644 --- 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 index 6d7852223..346d6eb2c 100644 --- 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'),