V3 documentation changes

jsdoc.json

@@ -3,6 +3,7 @@
     "include": [
       "packages/array-utils/src",
 
+      "packages/modeling/src",
       "packages/modeling/src/colors",
       "packages/modeling/src/curves",
       "packages/modeling/src/curves/bezier",
@@ -36,14 +37,20 @@
       "packages/modeling/src/utils",
 
       "packages/io/io-utils",
-      "packages/io/amf-deserializer/src",
-      "packages/io/amf-serializer",
+      "packages/io/3mf-deserializer/src",
+      "packages/io/3mf-serializer/src",
+      "packages/io/dxf-deserializer/src",
+      "packages/io/dxf-serializer/src",
+      "packages/io/json-deserializer/src",
+      "packages/io/json-serializer/src",
+      "packages/io/obj-deserializer/src",
+      "packages/io/obj-serializer/src",
+      "packages/io/stl-deserializer/src",
+      "packages/io/stl-serializer/src",
       "packages/io/svg-deserializer/src",
-      "packages/io/svg-serializer",
+      "packages/io/svg-serializer/src",
       "packages/io/x3d-deserializer/src",
-      "packages/io/x3d-serializer/src",
-      "packages/io/3mf-deserializer/src",
-      "packages/io/3mf-serializer/src"
+      "packages/io/x3d-serializer/src"
     ],
     "includePattern": ".+\\.js(doc|x)?$",
     "excludePattern": ".+test.js$"
@@ -86,8 +93,8 @@
       "url": ""
     },
     "meta": {
-      "title": "JSCAD API Documentation",
-      "description": "JSCAD API Documentation",
+      "title": "JSCAD V3 API Documentation",
+      "description": "JSCAD V3 API Documentation",
       "keyword": "JSCAD OpenJSCAD"
     },
     "search": [true],

jsdoc/assets/README.md

@@ -23,8 +23,8 @@ There are different 'flavors' of JSCAD that you can use based on your needs
 
 ## Documentation
 
-* [JSCAD User Guide](https://openjscad.xyz/guide.html)
-* [API Reference](https://openjscad.xyz/docs/)
+* [JSCAD User Guide](https://openjscad.xyz/v3/guide.html)
+* [API Reference](https://openjscad.xyz/v3/docs/)
 * [Open Issues](https://openjscad.xyz/issues.html)
 
 ## Community

jsdoc/tutorials/01_gettingStarted.md

@@ -23,34 +23,17 @@ it with the "Load a JSCAD Project" file dialog.
 The simplest file that will render a cube in JSCAD looks like this:
 ```javascript
 // the import statement allows your code to use JSCAD functions.
-import { primitives } from '@jscad/modeling'
+import { cube } from '@jscad/modeling'
 
 // the export statement defines the entry point of the design.
 export const main = () => {
-  return primitives.cube()
+  return cube()
 }
 ```
-JSCAD functions must be imported, but there are several different syntaxes for using the functions:
-```javascript
-// import one or more functional areas from JSCAD:
-import { primitives, booleans } from '@jscad/modeling'
-
-// use functions directly
-let aCube = primitives.cube()
-
-// or
-
-// use the functions by name
-const { cube, sphere } = primitives
-
-let aCube = cube()
-let aSphere = sphere()
-```
 ## Adding Methods
 Clean, readable code is one of the most important aspects of a useful design. In that respect, it can often be useful to break your code into simple function that do part of the work for your design:
 ```javascript
-import { primitives } from '@jscad/modeling'
-const { cylinder } = primitives
+import { cylinder } from '@jscad/modeling'
 
 const hex = (radius, height) => {
     return cylinder({radius, height, segments: 6})
@@ -63,8 +46,7 @@ export const main = () => {
 ## Re-usable Designs
 A valuable practise when creating models is to store all but the most trivial values as parameters in the code, rather than using the numerical values directly.  This can be done by storing them in constants in your file...
 ```javascript
-import { primitives } from '@jscad/modeling'
-const { cylinder } = primitives
+import { cylinder } from '@jscad/modeling'
 
 const options = {
     height: 5.1,
@@ -78,10 +60,10 @@ export const main = () => {
 
 ... or, even better, to include runtime parameters in your design.  This is done using the getParameterDefinitions function:
 ```javascript
-import { primitives } from '@jscad/modeling'
-const { cylinder } = primitives
+import { cylinder } from '@jscad/modeling'
 
 // Declare a function named "getParameterDefinitions". It will return an array of parameter definitions.
+// You must also export the getParameterDefinitions function.
 export const getParameterDefinitions = () => {
   return [
     { name: 'height', type: 'number', initial: 2.0, min: 1.0, max: 10.0, step: 0.1, caption: 'Hex Height:' },
@@ -93,7 +75,6 @@ export const getParameterDefinitions = () => {
 export const main = (params) => {
   return cylinder({radius: params.radius, height: params.height, segments: 6})
 }
-// You must also export the getParameterDefinitions function.
 ```
 <img src="img/parameters.png" alt="JSCAD Parameters Example">
 

jsdoc/tutorials/02_modelingBasics.md

@@ -38,9 +38,7 @@ Another valuable way of building shapes is to start with 2D shapes.  These can b
 specifying points, starting with basic primitive 2D shapes, or importing SVG files.  The 2D 
 shapes can then be extruded to produce a wide variety of different geometries.
 ```javascript
-import { primitives, extrusions } from '@jscad/modeling'
-const { polygon } = primitives
-const { extrudeLinear } = extrusions
+import { polygon, extrudeLinear } from '@jscad/modeling'
 
 export const main = () => {
     const poly = polygon({ points: [[-1, -1], [3, -1], [3.5, 2], [2, 1], [1, 2], [0, 1], [-1, 2]] })

jsdoc/tutorials/03_usingParameters.md

@@ -3,9 +3,7 @@ your designs, so that they can easily adapt to different situations.
 
 ## ParametricBox.js
 ```javascript
-import { primitives, booleans } from  '@jscad/modeling'
-const { cuboid, roundedCuboid } = primitives
-const { subtract } = booleans
+import { cuboid, roundedCuboid, subtract } from  '@jscad/modeling'
 
 export const getParameterDefinitions = () => {
   return [

jsdoc/tutorials/04_multifileProjects.md

@@ -21,14 +21,13 @@ contain your design. Your project can also contain:
 ```
 ## hexcap/index.js
 ```javascript
-import { primtives } from '@jscad/modeling'
-const { cylinder } = primitives
+import { cylinder } from '@jscad/modeling'
 
 import { hexWidthToRadius }  from './lib/utils.js'
 
 export const main = () => {
-  let hexRadius = utils.hexWidthToRadius(12)
-  return cylinder({radius: hexRadius, height: 4, segments: 6})
+  let radius = hexWidthToRadius(12)
+  return cylinder({radius, height: 4, segments: 6})
 }
 ```
 ## hexcap/lib/utils.js

jsdoc/tutorials/05_importingFiles.md

@@ -1,10 +1,11 @@
 Importing files in JSCAD is a simple case of loading them using the same import statement used to load javascript modules.  The files you load need to be part of a multifile project, so that JSCAD can access them:
 
 ```javascript
+// import all functions and global constants
 import * as jscad from '@jscad/modeling'
 
-const { translate, scale, rotateZ } = jscad.transforms
-const { union } = jscad.booleans
+// import specific functions and global constants by name
+const { translate, scale, rotateZ, union, TAU } = '@jscad/modeling'
 
 // Load the STL files using require
 const sculpture = require('./3d_sculpture-VernonBussler.stl')

packages/io/3mf-deserializer/src/index.js

@@ -42,7 +42,6 @@ const version = '[VI]{version}[/VI]' // version is injected by rollup
  * @param {String} [options.includedType] - type of 3MF objects to include, default is 'all'
  * @param {String} input - 3MF source data (OPC or XML)
  * @returns {(Array|String)} either an array of objects (geometry) or a string (script)
- * @alias module:io/3mf-deserializer.deserialize
  */
 const deserialize = (options, input) => {
   const defaults = {

packages/io/3mf-serializer/src/index.js

@@ -9,7 +9,7 @@
  *
  * @module io/3mf-serializer
  * @example
- * const { serializer, mimeType } = require('@jscad/3mf-serializer')
+ * import { serializer, mimeType } from '@jscad/3mf-serializer'
  */
 
 import { zipSync, strToU8 } from 'fflate'
@@ -24,6 +24,7 @@ const mimeType = 'model/3mf'
 /**
  * Serialize the give objects to 3MF contents (XML) or 3MF packaging (OPC).
  * @see https://3mf.io/specification/
+ *
  * @param {Object} [options] - options for serialization
  * @param {String} [options.unit='millimeter'] - unit of design; micron, millimeter, inch, feet, meter or micrometer
  * @param {Boolean} [options.metadata=true] - add metadata to 3MF contents, such at CreationDate

packages/io/dxf-deserializer/src/DxfReader.js

@@ -6,7 +6,7 @@ const STATES = [
   'error'
 ]
 
-/**
+/*
  * Class DxfReader
  * A class to hold state while reading DXF formatted data.
  * @param {Object} [options] - options for parsing

packages/io/dxf-deserializer/src/index.js

@@ -18,7 +18,7 @@ const version = '[VI]{version}[/VI]' // version is injected by rollup
  * Deserializer of DXF data to JSCAD geometries.
  * @module io/dxf-deserializer
  * @example
- * const { deserialize, extension } = require('@jscad/dxf-deserializer')
+ * import { deserialize, mimeType } from '@jscad/dxf-deserializer'
  */
 
 const handleError = (reader, error) => {
@@ -571,15 +571,15 @@ const translate = (src, options) => {
 
 /**
  * Deserialize the given DXF source into either a script or an array of geometry
+ *
  * @param {Object} options - options used during deserializing, REQUIRED
  * @param {string} [options.filename='dxf'] - filename of original DXF data stream
  * @param {String} [options.version] - version added to the script metadata, default is package version
  * @param {string} [options.output='script'] - either 'script' or 'geometry' to set desired output
  * @param {boolean} [options.strict=true] - obey strict DXF specifications
  * @param {array} [options.colorindex=[]] - list of colors (256) for use during rendering
  * @param {string} src - DXF data stream
- * @return {string|[objects]} a string (script) or array of objects (geometry)
- * @alias module:io/dxf-deserializer.deserialize
+ * @returns {(Array|String)} either an array of objects (geometry) or a string (script)
  */
 const deserialize = (options, src) => {
   const defaults = {

packages/io/dxf-serializer/src/index.js

@@ -8,19 +8,20 @@ const mimeType = 'image/vnd.dxf'
 
 /**
  * Serializer of JSCAD geometries to DXF entities.
+ *
  * @module io/dxf-serializer
  * @example
- * const { serializer, mimeType } = require('@jscad/dxf-serializer')
+ * import { serializer, mimeType } from '@jscad/dxf-serializer'
  */
 
 /**
  * Serialize the give objects to AutoCad DXF format.
+ *
  * @param {Object} options - options for serialization, REQUIRED
  * @param {String} [options.geom2To='lypolyline'] - target entity for 2D geometries, 'lwpolyline' or 'polyline'
  * @param {String} [options.geom3To='3dface'] - target entity for 3D geometries, '3dface' or 'polyline'
  * @param {Object|Array} objects - objects to serialize as DXF
  * @returns {Array} serialized contents, DXF format
- * @alias module:io/dxf-serializer.serialize
  * @example
  * const geometry = primitives.cube()
  * const dxfData = serializer({geom3To: '3dface'}, geometry)
@@ -60,7 +61,7 @@ EOF
   return [dxfContent]
 }
 
-/**
+/*
  * Serialize the given objects as a DXF entity section
  * @param {Array} objects - objects to serialize as DXF
  * @param {Object} options - options for serialization

packages/io/json-deserializer/src/index.js

@@ -10,7 +10,7 @@
  * @see https://www.json.org
  * @module io/json-deserializer
  * @example
- * const { deserializer, extension } = require('@jscad/json-deserializer')
+ * import { deserializer, mimeType } from '@jscad/json-deserializer'
  */
 
 import { flatten, toArray } from '@jscad/array-utils'
@@ -20,14 +20,14 @@ const version = '[VI]{version}[/VI]' // version is injected by rollup
 
 /**
  * Deserialize the given JSON notation (string) into either a script or an array of geometry.
+ *
  * @param {Object} options - options used during deserializing, REQUIRED
  * @param {String} [options.filename='json'] - filename of original JSON source
  * @param {String} [options.output='script'] - either 'script' or 'geometry' to set desired output
  * @param {String} [options.version='0.0.0'] - version number to add to the metadata
  * @param {Boolean} [options.addMetadata=true] - toggle injection of metadata at the start of the script
  * @param {String} input - JSON source data
- * @return {[geometry]/String} either an array of objects (geometry) or a string (script)
- * @alias module:io/json-deserializer.deserialize
+ * @return {(Array|String)} either an array of objects (geometry) or a string (script)
  */
 const deserialize = (options, input) => {
   const defaults = {

packages/io/json-serializer/src/index.js

@@ -2,7 +2,7 @@
  * Serializer of JSCAD geometries to JSON strings.
  * @module io/json-serializer
  * @example
- * const { serializer, mimeType } = require('@jscad/json-serializer')
+ * import { serializer, mimeType } from '@jscad/json-serializer'
  */
 
 import { flatten } from '@jscad/array-utils'
@@ -32,7 +32,6 @@ const replacer = (key, value) => {
  * @param {Object} options - options for serialization, REQUIRED
  * @param {Object|Array} objects - objects to serialize as JSON
  * @returns {Array} serialized contents as JSON string
- * @alias module:io/json-serializer.serialize
  * @example
  * const geometry = cube()
  * const jsonData = serializer({}, geometry)

packages/io/obj-deserializer/src/index.js

@@ -7,20 +7,20 @@ const version = '[VI]{version}[/VI]' // version is injected by rollup
  * Deserializer of OBJ data to JSCAD geometries.
  * @module io/obj-deserializer
  * @example
- * const { deserializer, extension } = require('@jscad/obj-deserializer')
+ * import { deserializer, mimeType } from '@jscad/obj-deserializer'
  */
 
 /**
  * Parse the given OBJ data and return either a JSCAD script or a set of geometry
  * @see http://en.wikipedia.org/wiki/Wavefront_.obj_file
+ *
  * @param {Object} options - options used during deserializing, REQUIRED
  * @param {string} [options.filename='obj'] - filename of the original obj data
  * @param {string} [options.version='0.0.0'] - version number to add to the metadata
  * @param {boolean} [options.addMetadata=true] - toggle injection of metadata at the start of the script
  * @param {string} [options.output='script'] - either 'script' or 'geometry' to set desired output
  * @param  {string} input - obj data
- * @return {[object]/string} either a script (script) or a set of objects (geometry)
- * @alias module:io/obj-deserializer.deserialize
+ * @return {(Array|string)} either a script (script) or a set of objects (geometry)
  */
 const deserialize = (options, input) => {
   const defaults = {

packages/io/obj-serializer/src/index.js

@@ -6,7 +6,7 @@
  *
  * @module io/obj-serializer
  * @example
- * const { serializer, mimeType } = require('@jscad/obj-serializer')
+ * import { serializer, mimeType } from '@jscad/obj-serializer'
  */
 
 import { cssColors, generalize, geom3 } from '@jscad/modeling'
@@ -22,7 +22,6 @@ const mimeType = 'model/obj'
  * @param {Function} [options.statusCallback] - call back function for progress ({ progress: 0-100 })
  * @param {...Object} objects - objects to serialize into OBJ source data
  * @returns {Array} serialized contents, OBJ source data
- * @alias module:io/obj-serializer.serialize
  * @example
  * const geometry = cube()
  * const objData = serializer({}, geometry)
@@ -96,12 +95,12 @@ const serialize = (options, ...objects) => {
   return [body]
 }
 
-/**
+/*
  * Convert a vertex to an obj "v" string
  */
 const convertVertex = (vertex) => `v ${vertex[0]} ${vertex[1]} ${vertex[2]}`
 
-/**
+/*
  * Get the closest css color name
  */
 const getColorName = (object) => {

packages/io/stl-deserializer/src/index.js

@@ -16,19 +16,19 @@ const pkgversion = '[VI]{version}[/VI]' // version is injected by rollup
  * Deserializer of STL data to JSCAD geometries.
  * @module io/stl-deserializer
  * @example
- * const { deserializer, extension } = require('@jscad/stl-deserializer')
+ * import { deserializer, extension } from '@jscad/stl-deserializer'
  */
 
 /**
  * Parse the given STL data and return either a JSCAD script or a list of geometries
+ *
  * @param {Object} options - options used during deserializing, REQUIRED
  * @param {string} [options.filename='stl'] - filename of original STL source
  * @param {string} [options.version='0.0.0'] - version number to add to the metadata
  * @param {boolean} [options.addMetadata=true] - toggle injection of metadata at the start of the script
  * @param {string} [options.output='script'] - either 'script' or 'geometry' to set desired output
  * @param {string} input - stl data
- * @return {[objects]|string} a list of objects (geometry) or a string (script)
- * @alias module:io/stl-deserializer.deserialize
+ * @return {(Array|string)} a list of objects (geometry) or a string (script)
  */
 const deserialize = (options, stl) => {
   const defaults = {