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",
@@ -35,15 +36,22 @@
       "packages/modeling/src/text",
       "packages/modeling/src/utils",
 
+      "packages/io/io/src",
       "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$"
@@ -54,7 +62,7 @@
     "tutorials": "./jsdoc/tutorials",
     "readme": "./jsdoc/assets/README.md"
   },
-  "plugins": ["plugins/markdown"],
+  "plugins": ["jsdoc/jsdocFix","plugins/markdown"],
   "templates": {
     "default": {
       "staticFiles": {
@@ -86,8 +94,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/assets/static/jscad-docs.css

@@ -5,6 +5,7 @@ body {
 
 nav {
     background: none;
+    padding-bottom: 10px;
 }
 
 section {

jsdoc/jsdocFix.js

@@ -0,0 +1,9 @@
+const newDocletFix = (docHandle) => {
+  if (docHandle.doclet.params) {
+    docHandle.doclet.kind = "function"
+  }
+}
+
+exports.handlers = {
+  newDoclet: newDocletFix
+}

jsdoc/package.json

@@ -0,0 +1,3 @@
+{
+  "name": "package to fix jsdoc"
+}

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
@@ -177,7 +177,7 @@ const parse = (reader, data) => {
   return reader
 }
 
-/**
+/*
  * Parse the given line in the context of the given reader, emitting group value pairs
  * @param reader {DxfReader} - context DxfReader to use
  * @param line {String} - line to parse
@@ -200,7 +200,7 @@ const parseLine = (reader, line) => {
   }
 }
 
-/**
+/*
  * Parse the given line in the context of the given reader, and update the group
  * @param reader {DxfReader} - context DxfReader to use
  * @param line {String} - line to parse
@@ -216,7 +216,7 @@ const setDxfGroup = (reader, line) => {
   }
 }
 
-/**
+/*
  * Parse the given line in the context of the given reader, and update the (group) value
  * @param reader {DxfReader} - context DxfReader to use
  * @param line {String} - line to parse

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/io/src/deserialize.js

@@ -14,14 +14,17 @@ const transformers = {
 
 /**
  * Deserialize the given source as per the given mimeType.
+ *
  * Options can be provided to over-ride or suppliment the defaults used during deserialization.
- * Options must include 'output' as either 'script' or 'geometry'.
+ *
  * @param {Object} options - options used during deserializing
  * @param {String} mimeType - MIME type of the file
  * @param {String} source - the contents of the file
- * @return {[objects]|string} a list of objects (geometry) or a string (script)
+ * @returns {(Array|String)} either an array of objects (geometry) or a string (script)
+ * @alias module:io.deserialize
  *
  * @example
+ * import { getMimeType, deserialize } from '@jscad/io'
  * const mimetype = getMimeType('svg')
  * const myobjects = deserialize({output: 'geometry', target: 'path2'}, mimetype, source)
  */

packages/io/io/src/index.js

@@ -1,3 +1,6 @@
+/**
+ * @module io
+ */
 export { deserialize } from './deserialize.js'
 export { deserializers } from './deserializers.js'
 

packages/io/io/src/serialize.js

@@ -4,14 +4,18 @@ import { serializers } from './serializers.js'
 
 /**
  * Serialize the given objects as per the given mimeType into the external format.
+ *
  * Options can be provided to over-ride or suppliment the defaults used during serialization.
- * See each serializer package for available options.
+ * @See each serializer package for available options.
+ *
  * @param {Object} options - options used during deserializing
  * @param {String} mimeType - MIME type of the file
  * @param {Object} objects - one or more objects of which to serialize
  * @return {Object} an object containing the serialize data as well as mime type
+ * @alias module:io.serialize
  *
  * @example
+ * import { getMimeType, serialize } from '@jscad/io'
  * const mimetype = getMimeType('svg')
  * const shapes = [primitives.cirlce(), primitives.star()]
  * const output = serialize({units: 'inches'}, mimetype, shapes)