docs(modeling): adjusted docs to use imports, added more examples

Author: z3dev

packages/modeling/src/geometries/geom2/applyTransforms.js

@@ -3,12 +3,14 @@ import * as vec2 from '../../maths/vec2/index.js'
 
 /*
  * Apply the transforms of the given geometry.
+ *
  * NOTE: This function must be called BEFORE exposing any data. See toOutlines().
+ *
  * @param {Geom2} geometry - the geometry to transform
  * @returns {Geom2} the given geometry
  *
  * @example
- * geometry = applyTransforms(geometry)
+ * const geometry = geom2.applyTransforms(geometry)
  */
 export const applyTransforms = (geometry) => {
   if (mat4.isIdentity(geometry.transforms)) return geometry

packages/modeling/src/geometries/geom2/clone.js

@@ -1,7 +1,11 @@
 /**
  * Performs a shallow clone of the given geometry.
+ *
  * @param {Geom2} geometry - the geometry to clone
  * @returns {Geom2} new geometry
- * @alias module:modeling/geometries/geom2.clone
+ * @alias module:modeling/geom2.clone
+ *
+ * @example
+ * const geometry = geom2.clone(geometry)
  */
 export const clone = (geometry) => Object.assign({}, geometry)

packages/modeling/src/geometries/geom2/create.js

@@ -1,24 +1,14 @@
 import * as mat4 from '../../maths/mat4/index.js'
 
-/**
- * Represents a 2D geometry consisting of outlines, where each outline is an ordered list of points.
- * @property {Array} outlines - list of polygon outlines
- * @property {Mat4} transforms - transforms to apply to the geometry, see transform()
- * @example
- * // data structure
- * {
- *   "outlines": [[[-1,-1],[1,-1],[1,1],[-1,1]]],
- *   "transforms": [1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1]
- * }
- */
-
 /**
  * Create a new 2D geometry composed of polygon outlines.
+ *
  * @param {Array} [outlines] - list of outlines where each outline is an array of points
  * @returns {Geom2} a new geometry
- * @alias module:modeling/geometries/geom2.create
+ * @alias module:modeling/geom2.create
+ *
  * @example
- * let myShape = create([ [[-1,-1], [1,-1], [1,1], [-1,1]] ])
+ * let myShape = geom2.create([ [[-1,-1], [1,-1], [1,1], [-1,1]] ])
  */
 export const create = (outlines = []) => ({
   outlines,

packages/modeling/src/geometries/geom2/fromSides.js

@@ -26,7 +26,7 @@ const toSharedPoints = (sides) => {
  */
 const toPointMap = (sides) => {
   const pointMap = new Map()
-  // first map to edges with shared vertices
+  // first map to edges with shared points
   const edges = toSharedPoints(sides)
   // construct adjacent edges map
   edges.forEach((edge) => {
@@ -41,11 +41,13 @@ const toPointMap = (sides) => {
 
 /**
  * Create a new 2D geometry from a list of sides.
+ *
  * @param {Array} sides - list of sides to create outlines from
  * @returns {Geom2} a new geometry
+ * @alias module:modeling/geom2.fromSides
  *
  * @example
- * let geometry = fromSides([[[0, 0], [1, 0]], [[1, 0], [1, 1]], [[1, 1], [0, 0]]])
+ * let geometry = geom2.fromSides([[[0, 0], [1, 0]], [[1, 0], [1, 1]], [[1, 1], [0, 0]]])
  */
 export const fromSides = (sides) => {
   const pointMap = toPointMap(sides) // {point: [edges]}

packages/modeling/src/geometries/geom2/index.js

@@ -1,12 +1,28 @@
 /**
  * Represents a 2D geometry consisting of outlines, where each outline is an ordered list of points.
- * The outline is always closed between the first and last points.
- * @see {@link geom2} for data structure information.
- * @module modeling/geometries/geom2
+ *
+ * Each outline is always closed between the first and last points.
+ *
+ * @see {@link Geom2} for data structure information.
+ * @module modeling/geom2
+ *
+ * @example
+ * import { geom2 } from '@jscad/modeling'
+ * let myShape = geom2.create([ [[-1,-1], [1,-1], [1,1], [-1,1]] ])
+ */
+
+/**
+ * @typedef Geom2
+ * @type {Object}
+ * @property {Array} outlines - list of outlines, each outline is an ordered list of points
+ * @property {Mat4} transforms - transforms to apply to the polygons, see transform()
  *
  * @example
- * import { geometries } from '@jscad/modeling'
- * let myShape = geometries.geom2.create([ [[-1,-1], [1,-1], [1,1], [-1,1]] ])
+ * // data structure
+ * {
+ *   "outlines": [[[-1,-1],[1,-1],[1,1],[-1,1]]],
+ *   "transforms": [1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1]
+ * }
  */
 export { clone } from './clone.js'
 export { create } from './create.js'

packages/modeling/src/geometries/geom2/isA.js

@@ -1,8 +1,12 @@
 /**
  * Determine if the given object is a 2D geometry.
+ *
  * @param {object} object - the object to interrogate
  * @returns {Boolean} true, if the object matches a geom2 based object
- * @alias module:modeling/geometries/geom2.isA
+ * @alias module:modeling/geom2.isA
+ *
+ * @example
+ * const geometry = geom2.isA(geometry)
  */
 export const isA = (object) => {
   if (object && typeof object === 'object') {

packages/modeling/src/geometries/geom2/reverse.js

@@ -3,13 +3,15 @@ import { toOutlines } from './toOutlines.js'
 
 /**
  * Reverses the given geometry so that the outline points are flipped in the opposite order.
+ *
  * This swaps the left (interior) and right (exterior) edges.
+ *
  * @param {Geom2} geometry - the geometry to reverse
  * @returns {Geom2} the new reversed geometry
- * @alias module:modeling/geometries/geom2.reverse
+ * @alias module:modeling/geom2.reverse
  *
  * @example
- * let newGeometry = reverse(geometry)
+ * let newGeometry = geom2.reverse(geometry)
  */
 export const reverse = (geometry) => {
   const outlines = toOutlines(geometry)

packages/modeling/src/geometries/geom2/toOutlines.js

@@ -2,9 +2,10 @@ import { applyTransforms } from './applyTransforms.js'
 
 /**
  * Create the outline(s) of the given geometry.
+ *
  * @param {Geom2} geometry - geometry to create outlines from
  * @returns {Array} an array of outlines, where each outline is an array of ordered points
- * @alias module:modeling/geometries/geom2.toOutlines
+ * @alias module:modeling/geom2.toOutlines
  *
  * @example
  * let geometry = subtract(rectangle({size: [5, 5]}), rectangle({size: [3, 3]}))

packages/modeling/src/geometries/geom2/toPoints.js

@@ -2,14 +2,17 @@ import { toOutlines } from './toOutlines.js'
 
 /**
  * Produces an array of points from the given geometry.
+ *
  * The returned array should not be modified as the points are shared with the geometry.
+ *
  * NOTE: The points returned do NOT define an order. Use toOutlines() for ordered points.
+ *
  * @param {Geom2} geometry - the geometry
  * @returns {Array} an array of points
- * @alias module:modeling/geometries/geom2.toPoints
+ * @alias module:modeling/geom2.toPoints
  *
  * @example
- * let sharedPoints = toPoints(geometry)
+ * let sharedPoints = geom2.toPoints(geometry)
  */
 export const toPoints = (geometry) => {
   const points = []

packages/modeling/src/geometries/geom2/toSides.js

@@ -2,14 +2,15 @@ import { toOutlines } from './toOutlines.js'
 
 /**
  * Produces an array of sides from the given geometry.
- * The returned array should not be modified as the data is shared with the geometry.
+ *
  * NOTE: The sides returned do NOT define an order. Use toOutlines() for ordered points.
+ *
  * @param {Geom2} geometry - the geometry
  * @returns {Array} an array of sides
- * @alias module:modeling/geometries/geom2.toSides
+ * @alias module:modeling/geom2.toSides
  *
  * @example
- * let sharedSides = toSides(geometry)
+ * let sharedSides = geom2.toSides(geometry)
  */
 export const toSides = (geometry) => {
   const sides = []