api(all): cleanup JSDoc formatting and standardize API examples

The JSDoc syntax was incorrect on several matchers. This did not affect usability, but was causing linting issues. The API documentation is now standardized, formatted well, and each matcher has an example for testing both true and false cases. The matcher examples are also enclosed within a test block for better demonstration of where to use it.
M-Scott-Lassiter · May 30, 2022 · 300a96d · 300a96d
1 parent ed7c3eb
commit 300a96d
Show file tree

Hide file tree

Showing 28 changed files with 567 additions and 473 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -88,13 +88,13 @@ To submit a pull request,
     -   [ ] Create a core function under `src/core/<category>`
     -   [ ] Register the core function in `src/core.js`
     -   [ ] Add a verification test to `tests/core.test.js`
-    -   [ ] Document the function using JSDoc. Refer to the issue.
+    -   [ ] Document the function using JSDoc. Refer to the issue. Include good and bad examples.
 -   <u>Create Matcher Function</u>
     -   [ ] Create a matcher function under `src/matchers/<category>`
     -   [ ] Register the matcher in `src/matchers.js`
     -   [ ] Add a verification test to `matchers.test.js`
     -   [ ] Add the matcher to the `.cz-config.js` list (alphabetical order under the `coordinateMatchers` variable)
-    -   [ ] Document the matcher using JSDoc. Refer to the issue.
+    -   [ ] Document the matcher using JSDoc. Refer to the issue. Include good and bad examples.
 -   [ ] Create a test for the matcher under `tests/<category>`
 -   [ ] Verify all tests pass and have 100% coverage
 -   [ ] Add the matcher to the README.md list (alphabetical order within category)

diff --git a/README.md b/README.md
@@ -37,7 +37,6 @@
 -   [Getting Started](#getting-started)
     -   [Install as a Dependency](#install-as-a-dependency)
     -   [Configure Jest](#configure-jest)
--   [Import the Core Engine](#import-the-core-engine)
 -   [Matchers](#matchers)
     -   [Coordiantes](#coordiantes)
     -   [Bounding Boxes](#bounding-boxes)
@@ -46,6 +45,8 @@
     -   [Features](#features)
     -   [Feature Collections](#feature-collections)
     -   [Functional](#functional)
+-   [Advanced Configuration](#advanced-configuration)
+    -   [Import the Core Engine](#import-the-core-engine)
 -   [License and Development](#license-and-development)
 -   [Contact](#contact)
 
@@ -115,18 +116,6 @@ The matchers object contains each matcher grouped by category.
 
 <!-- add link to documentation when online -->
 
-# Import the Core Engine
-
-You can import the functions that drive the test matchers.
-
-```javascript
-const core = require('jest-geojson/core')
-```
-
-The core object contains the functions grouped by category. You can then use these functions elsewhere in your code, or even port `jest-geojson` into another testing framework.
-
-<!-- add link to documentation when online -->
-
 # Matchers
 
 `jest-geojson` organizes matchers by categories that correspond to the input type passed to `expect()`.
@@ -262,7 +251,19 @@ _Future_
 -   [ ] isInEasternernHemisphere
 -   [ ] isInWesternHemisphere
 
----
+# Advanced Configuration
+
+## Import the Core Engine
+
+You can import the functions that drive the test matchers.
+
+```javascript
+const core = require('jest-geojson/core')
+```
+
+The core object contains the functions grouped by category. You can then use these functions elsewhere in your code, or even port `jest-geojson` into another testing framework.
+
+<!-- add link to documentation when online -->
 
 # License and Development
 

diff --git a/src/core/boundingBoxes/valid2DBoundingBox.js b/src/core/boundingBoxes/valid2DBoundingBox.js
@@ -12,9 +12,9 @@
  * @example
  * const goodBBox = valid2DBoundingBox([-10, -20, 20, -10]) // true
  * const crossesAntimeridian = valid2DBoundingBox([170, -20, -170, 20]) // true
- * @example
- * const badExample1 valid2DBoundingBox([-10, -200, 20, -10]) // throws error for south being out of range
- * const badExample2 valid2DBoundingBox([-10, -20, '20', -10]) // throws error for non-numeric value
+ *
+ * const badExample1 = valid2DBoundingBox([-10, -200, 20, -10]) // throws error for south being out of range
+ * const badExample2 = valid2DBoundingBox([-10, -20, '20', -10]) // throws error for non-numeric value
  */
 function valid2DBoundingBox(bboxArray) {
     if (!Array.isArray(bboxArray) || bboxArray.length !== 4) {

diff --git a/src/core/boundingBoxes/valid3DBoundingBox.js b/src/core/boundingBoxes/valid3DBoundingBox.js
@@ -15,9 +15,9 @@ const { valid2DBoundingBox } = require('./valid2DBoundingBox')
  * @example
  * const goodBBox = valid3DBoundingBox([-10, -20, -100, 20, 10, 0]) // true
  * const crossesAntimeridian = valid3DBoundingBox([170, -20, -22.5, 20, -170, 12345.678]) // true
- * @example
- * const badExample1 valid3DBoundingBox([-10, -91, 0, 10, 20, 0]) // throws error for south being out of range
- * const badExample2 valid3DBoundingBox([-10, -10, "0", 10, 20, 0]) // throws error for non-numeric value
+ *
+ * const badExample1 = valid3DBoundingBox([-10, -91, 0, 10, 20, 0]) // throws error for south being out of range
+ * const badExample2 = valid3DBoundingBox([-10, -10, "0", 10, 20, 0]) // throws error for non-numeric value
  */
 function valid3DBoundingBox(bboxArray) {
     if (!Array.isArray(bboxArray) || bboxArray.length !== 6) {

diff --git a/src/core/boundingBoxes/validBoundingBox.js b/src/core/boundingBoxes/validBoundingBox.js
@@ -14,6 +14,12 @@ const { valid3DBoundingBox } = require('./valid3DBoundingBox')
  * The standard does not specify units altitude represents (i.e. meters, feet, etc.).
  * @returns {boolean} True if a valid 2D or 3D GeoJSON bounding box. If invalid, it will throw an error.
  * @throws {Error} Input must be an array of only four or six elments
+ * @example
+ * const good2DBBox = validBoundingBox([-10, -20, 20, -10]) // true
+ * const good3DBBox = validBoundingBox([-10, -20, -100, 20, 10, 0]) // true
+ *
+ * const badExample1 = validBoundingBox([-10, -91, 10, 20]) // throws error for south being out of range
+ * const badExample2 = validBoundingBox([-10, -10, "0", 10, 20, 0]) // throws error for non-numeric value
  */
 function validBoundingBox(bboxArray) {
     if (!Array.isArray(bboxArray)) {

diff --git a/src/core/coordinates/valid2DCoordinate.js b/src/core/coordinates/valid2DCoordinate.js
@@ -8,6 +8,11 @@
  * @throws {Error} Input must be an array of only two elments
  * @throws {RangeError} Longitude must be a number between -180 and 180
  * @throws {RangeError} Latitude must be a number between -90 and 90
+ * @example
+ * const goodCoord = valid2DCoordinate([10, 20]) // true
+ *
+ * const badExample1 = valid2DBoundingBox([10, -200]) // throws error for latitude being out of range
+ * const badExample2 = valid2DBoundingBox([10, 20, 0]) // throws error for 3D Coordinate
  */
 function valid2DCoordinate(coordinate) {
     if (!Array.isArray(coordinate) || coordinate.length !== 2) {

diff --git a/src/core/coordinates/valid3DCoordinate.js b/src/core/coordinates/valid3DCoordinate.js
@@ -9,6 +9,12 @@ const { valid2DCoordinate } = require('./valid2DCoordinate')
  * @returns {boolean} True if a valid 3D GeoJSON coordinate. If invalid, it will throw an error.
  * @throws {Error} Input must be an array of only three elments
  * @throws {Error} Altitude value must be numeric
+ * @example
+ * const goodCoord = valid3DCoordinate([10, 20, 0]) // true
+ *
+ * const badExample1 = valid3DBoundingBox([10, -200, 0]) // throws error for latitude being out of range
+ * const badExample2 = valid3DBoundingBox([10, 20, '0']) // throws error for altitude being a string instead of number
+ * const badExample3 = valid3DBoundingBox([10, 0]) // throws error for 2D Coordinate
  */
 function valid3DCoordinate(coordinate) {
     if (!Array.isArray(coordinate) || coordinate.length !== 3) {

diff --git a/src/core/coordinates/validCoordinate.js b/src/core/coordinates/validCoordinate.js
@@ -9,6 +9,12 @@ const { valid3DCoordinate } = require('./valid3DCoordinate')
  * @param {number[]} coordinate A WGS-84 array of [longitude, latitude] or [longitude, latitude, alititude]
  * @returns {boolean} True if a valid 2D or 3D GeoJSON coordinate. If invalid, it will throw an error.
  * @throws {Error} Input must be an array of only two or three elments
+ * @example
+ * const goodCoord1 = validCoordinate([10, 20]) // true
+ * const goodCoord2 = validCoordinate([10, 20, 0]) // true
+ *
+ * const badExample1 = validCoordinate([10, -200]) // throws error for latitude being out of range
+ * const badExample2 = validCoordinate([10, 20, '0']) // throws error for altitude being a string instead of number
  */
 function validCoordinate(coordinate) {
     if (!Array.isArray(coordinate) || coordinate.length < 2 || coordinate.length > 3) {

diff --git a/src/core/geometries/anyGeometry.js b/src/core/geometries/anyGeometry.js
@@ -15,47 +15,47 @@ const { multiPolygonGeometry } = require('./multiPolygonGeometry')
  * @returns {boolean} True if a valid GeoJSON geometry object. If invalid, it will throw an error.
  * @throws {Error} Input must be either a valid Point, MultiPoint, LineString, MultiLineString, Polygon, or MultiPolygon
  * @example
-point = {
-    "type": "Point",
-    "coordinates": [100.0, 0.0]
-}
-lineString = {
-    "type": "LineString",
-    "coordinates": [
-        [
-            [180.0, 40.0],
-            [180.0, 50.0],
-            [170.0, 50.0],
-            [170.0, 40.0],
-            [180.0, 40.0]
-        ]
-    ]
-}
-polygon = {
-    "type": "Polygon",
-    "coordinates": [
-        [
-            [100.0, 0.0],
-            [101.0, 0.0],
-            [101.0, 1.0],
-            [100.0, 1.0],
-            [100.0, 0.0]
-        ]
-    ]
-}
-feature = {
-    "type": "Feature",
-    "geometry": {
-        "type": "Point",
-        "coordinates": [102.0, 0.5]
-    }
-}
- 
-console.log(anyGeometry(point)) // true
-console.log(anyGeometry(lineString)) // true
-console.log(anyGeometry(polygon)) // true
- 
-console.log(anyGeometry(feature)) // throws error
+ * point = {
+ *     type: 'Point',
+ *     coordinates: [100.0, 0.0]
+ * }
+ * lineString = {
+ *     type: 'LineString',
+ *     coordinates: [
+ *         [
+ *             [180.0, 40.0],
+ *             [180.0, 50.0],
+ *             [170.0, 50.0],
+ *             [170.0, 40.0],
+ *             [180.0, 40.0]
+ *         ]
+ *     ]
+ * }
+ * polygon = {
+ *     type: 'Polygon',
+ *     coordinates: [
+ *         [
+ *             [100.0, 0.0],
+ *             [101.0, 0.0],
+ *             [101.0, 1.0],
+ *             [100.0, 1.0],
+ *             [100.0, 0.0]
+ *         ]
+ *     ]
+ * }
+ * feature = {
+ *     type: 'Feature',
+ *     geometry: {
+ *         type: 'Point',
+ *         coordinates: [102.0, 0.5]
+ *     }
+ * }
+ *
+ * const goodExample1 = anyGeometry(point)) // true
+ * const goodExample2 = anyGeometry(lineString)) // true
+ * const goodExample3 = anyGeometry(polygon)) // true
+ *
+ * const badExample = anyGeometry(feature)) // throws error
  */
 function anyGeometry(geometryObject) {
     // if (

diff --git a/src/core/geometries/lineStringGeometry.js b/src/core/geometries/lineStringGeometry.js
@@ -17,21 +17,22 @@ const { validCoordinate } = require('../coordinates/validCoordinate')
  * @throws {Error} forbidden from having a property 'geometry', 'properties', or 'features'
  * @example
  * const linestring = {
-        "type": "LineString",
-        "coordinates": [
-            [
-                [180.0, 40.0], [180.0, 50.0], [170.0, 50.0],
-                [170.0, 40.0], [180.0, 40.0]
-            ]
-        ]
-    }
-    const point = {
-        type: "Point",
-        coordinates: [100.0, 0.0]
-    }
- 
-    console.log(lineStringGeometry(linestring)) // true
-    console.log(lineStringGeometry(point)) // throws error
+ *     type: 'LineString',
+ *     coordinates: [
+ *         [
+ *             [180.0, 40.0], [180.0, 50.0], [170.0, 50.0],
+ *             [170.0, 40.0], [180.0, 40.0]
+ *         ]
+ *     ]
+ * }
+ * const point = {
+ *     type: 'Point',
+ *     coordinates: [100.0, 0.0]
+ * }
+ *
+ * const goodExample = lineStringGeometry(linestring) // true
+ *
+ * const badExample = lineStringGeometry(point)) / throws error
  */
 function lineStringGeometry(geometryObject) {
     if (

diff --git a/src/core/geometries/multiLineStringGeometry.js b/src/core/geometries/multiLineStringGeometry.js
@@ -4,8 +4,8 @@ const { validCoordinate } = require('../coordinates/validCoordinate')
  * Verifies an object is a valid GeoJSON MultiLineString Geometry. This geometry requires a
  * 'type' property that must equal "MultiLineString", and a 'coordinates' property that contains
  * an array of linestring arrays (i.e. each linestring array containing at least two or more valid
- * WGS-84 GeoJSON coordinates). 
- * 
+ * WGS-84 GeoJSON coordinates).
+ *
  * The coordinates may be an empty array, but may not be an array of empty arrays.
  *
  * Foreign members are allowed with the exceptions thrown below.
@@ -20,34 +20,35 @@ const { validCoordinate } = require('../coordinates/validCoordinate')
  * @throws {Error} forbidden from having a property 'geometry', 'properties', or 'features'
  * @example
  * const multiLineString = {
-        "type": "MultiLineString",
-        "coordinates": [
-            [
-                [100.0, 0.0],
-                [101.0, 1.0]
-            ],
-            [
-                [102.0, 2.0],
-                [103.0, 3.0]
-            ]
-        ]
-    }
-    const multiLineStringOneCoordinate = {
-        "type": "MultiLineString",
-        "coordinates": [
-            [
-                [100.0, 0.0]
-            ]
-        ]
-    }
-    const point = {
-        type: "Point",
-        coordinates: [100.0, 0.0]
-    }
- 
-    console.log(multiLineStringGeometry(multiLineString)) // true
-    console.log(multiLineStringGeometry(point)) // throws error
-    console.log(multiLineStringGeometry(multiLineStringOneCoordinate)) // throws error
+ *     type: 'MultiLineString',
+ *     coordinates: [
+ *         [
+ *             [100.0, 0.0],
+ *             [101.0, 1.0]
+ *         ],
+ *         [
+ *             [102.0, 2.0],
+ *             [103.0, 3.0]
+ *         ]
+ *     ]
+ * }
+ * const multiLineStringOneCoordinate = {
+ *     type: 'MultiLineString',
+ *     coordinates: [
+ *         [
+ *             [100.0, 0.0]
+ *         ]
+ *     ]
+ * }
+ * const point = {
+ *     type: 'Point',
+ *     coordinates: [100.0, 0.0]
+ * }
+ *
+ * const goodExample = multiLineStringGeometry(multiLineString) // true
+ *
+ * const badExample1 = multiLineStringGeometry(point) // throws error
+ * const badExample2 = multiLineStringGeometry(multiLineStringOneCoordinate) // throws error
  */
 function multiLineStringGeometry(geometryObject) {
     if (

diff --git a/src/core/geometries/multiPointGeometry.js b/src/core/geometries/multiPointGeometry.js
@@ -17,18 +17,19 @@ const { validCoordinate } = require('../coordinates/validCoordinate')
  * @throws {Error} forbidden from having a property 'geometry', 'properties', or 'features'
  * @example
  * const testMultiPoint1 = {
-        type: "MultiPoint",
-        id: null,
-        coordinates: [[25, 90], [-180, 0]]
-    }
- 
-    const testMultiPoint2 = {
-        type: "Point",
-        coordinates: [25, 90]
-    }
- 
-    console.log(multiPointGeometry(testMultiPoint1)) // true
-    console.log(multiPointGeometry(testMultiPoint2)) // throws error
+ *     type: 'MultiPoint',
+ *     id: null,
+ *     coordinates: [[25, 90], [-180, 0]]
+ * }
+ *
+ * const testMultiPoint2 = {
+ *     type: 'Point',
+ *     coordinates: [25, 90]
+ * }
+ *
+ * const goodExample = console.log(multiPointGeometry(testMultiPoint1) // true
+ *
+ * const badExample = console.log(multiPointGeometry(testMultiPoint2) // throws error
  */
 function multiPointGeometry(geometryObject) {
     if (