docs: introduce / simplify documentation

Author: nikku

intersect.d.ts

@@ -28,11 +28,11 @@
  * //   { x: 50, y: 50, segment1: 1, segment2: 1, t1: 0.5, t2: 0.5 }
  * // ];
  *
- * @param {String|Array<PathComponent>} path1
- * @param {String|Array<PathComponent>} path2
- * @param {Boolean} [justCount=false]
+ * @param {Path} path1
+ * @param {Path} path2
+ * @param {boolean} [justCount=false]
  *
- * @return {Array<Intersection>|Number}
+ * @return {Intersection[]|number}
  */
 declare function findPathIntersections(path1: Path, path2: Path, justCount: true): number;
 declare function findPathIntersections(path1: Path, path2: Path, justCount: false): Intersection[];
@@ -72,12 +72,13 @@ export function parsePath(path: Path): PathComponent[];
 /**
  * A string in the form of 'M150,150m0,-18a18,18,0,1,1,0,36a18,18,0,1,1,0,-36z'
  * or something like:
+ *
  * [
- *  ['M', 1, 2],
- *  ['m', 0, -2],
- *  ['a', 1, 1, 0, 1, 1, 0, 2 * 1],
- *  ['a', 1, 1, 0, 1, 1, 0, -2 * 1],
- *  ['z']
+ *   ['M', 1, 2],
+ *   ['m', 0, -2],
+ *   ['a', 1, 1, 0, 1, 1, 0, 2 * 1],
+ *   ['a', 1, 1, 0, 1, 1, 0, -2 * 1],
+ *   ['z']
  * ]
  */
 declare type Path = string | PathComponent[];

intersect.js

@@ -4,6 +4,11 @@
  * @see https://github.com/adobe-webplatform/Snap.svg/blob/master/src/path.js
  */
 
+/**
+ * @typedef { import('./intersect.js').PathComponent } PathComponent
+ * @typedef { import('./intersect.js').Path } Path
+ */
+
 /* eslint no-fallthrough: "off" */
 
 var p2s = /,?([a-z]),?/gi,
@@ -69,6 +74,13 @@ function cacher(f) {
   return newf;
 }
 
+/**
+ * Parse SVG path string and return an array of path components.
+ *
+ * @param {string} pathString
+ *
+ * @return {PathComponent[]}
+ */
 function parsePathString(pathString) {
 
   if (!pathString) {
@@ -105,6 +117,13 @@ function parsePathString(pathString) {
   return pathComponents;
 }
 
+/**
+ * Checks if a path is already in absolute format.
+ * An absolute path has all uppercase commands.
+ *
+ * @param {PathComponent[]} pathComponents
+ * @return {boolean}
+ */
 function isPathAbsolute(pathComponents) {
 
   for (var i = 0; i < pathComponents.length; i++) {
@@ -117,13 +136,17 @@ function isPathAbsolute(pathComponents) {
   return true;
 }
 
-function isPathCurve(pathArray) {
-  if (!isArray(pathArray) || !pathArray.length) {
-    return false;
-  }
-
-  for (var i = 0; i < pathArray.length; i++) {
-    var command = pathArray[i][0];
+/**
+ * Checks if a path is already in curve format.
+ * A curve path only contains 'M' and 'C' commands.
+ *
+ * @param {PathComponent[]} pathComponents
+ *
+ * @return {boolean}
+ */
+function isPathCurve(pathComponents) {
+  for (var i = 0; i < pathComponents.length; i++) {
+    var command = pathComponents[i][0];
     if (command !== 'M' && command !== 'C') {
       return false;
     }
@@ -155,8 +178,13 @@ function pathToString() {
   return this.join(',').replace(p2s, '$1');
 }
 
-function pathClone(pathArray) {
-  var res = clone(pathArray);
+/**
+ * @param {PathComponent[]} pathComponents
+ *
+ * @return {PathComponent[]}
+ */
+function pathClone(pathComponents) {
+  var res = clone(pathComponents);
   res.toString = pathToString;
   return res;
 }
@@ -389,11 +417,11 @@ function findBezierIntersections(bez1, bez2, justCount) {
  * //   { x: 50, y: 50, segment1: 1, segment2: 1, t1: 0.5, t2: 0.5 }
  * // ]
  *
- * @param {String|Array<PathDef>} path1
- * @param {String|Array<PathDef>} path2
- * @param {Boolean} [justCount=false]
+ * @param {Path} path1
+ * @param {Path} path2
+ * @param {boolean} [justCount=false]
  *
- * @return {Array<Intersection>|Number}
+ * @return {Intersection[]|number}
  */
 export default function findPathIntersections(path1, path2, justCount) {
   path1 = pathToCurve(path1);
@@ -461,14 +489,26 @@ export default function findPathIntersections(path1, path2, justCount) {
   return res;
 }
 
+/**
+ * Test if path is a set of path components [ ['M', 0, 0 ], ['L', 100, 100], ...].
+ *
+ * @param {Path} path
+ *
+ * @return {boolean}
+ */
 function isPathComponents(path) {
   return isArray(path) && isArray(path[0]);
 }
 
-function pathToAbsolute(pathArray) {
+/**
+ * @param {PathComponent[]} pathComponents
+ *
+ * @return {PathComponent[]}
+ */
+function pathToAbsolute(pathComponents) {
 
-  if (isPathAbsolute(pathArray)) {
-    return pathArray;
+  if (isPathAbsolute(pathComponents)) {
+    return pathComponents;
   }
 
   var res = [],
@@ -479,18 +519,18 @@ function pathToAbsolute(pathArray) {
       start = 0,
       pa0;
 
-  if (pathArray[0][0] == 'M') {
-    x = +pathArray[0][1];
-    y = +pathArray[0][2];
+  if (pathComponents[0][0] == 'M') {
+    x = +pathComponents[0][1];
+    y = +pathComponents[0][2];
     mx = x;
     my = y;
     start++;
     res[0] = [ 'M', x, y ];
   }
 
-  for (var r, pa, i = start, ii = pathArray.length; i < ii; i++) {
+  for (var r, pa, i = start, ii = pathComponents.length; i < ii; i++) {
     res.push(r = []);
-    pa = pathArray[i];
+    pa = pathComponents[i];
     pa0 = pa[0];
 
     if (pa0 != pa0.toUpperCase()) {
@@ -768,6 +808,13 @@ function curveBBox(x0, y0, x1, y1, x2, y2, x3, y3) {
   };
 }
 
+/**
+ * Convert path to a curve.
+ *
+ * @param {Path} path
+ *
+ * @return {PathComponent[]}
+ */
 function pathToCurve(path) {
 
   if (!isPathComponents(path)) {