Add and update ESLint tests for Mapbox GL JS API docs

.circleci/config.yml

@@ -157,7 +157,6 @@ jobs:
             - v2-lint-{{ .Branch }}
             - v2-lint
       - run: yarn run lint
-      - run: yarn run lint-docs
       - run: yarn run lint-css
       - save_cache:
           key: v2-lint-{{ .Branch }}-{{ .Revision }}

.eslintrc

@@ -15,7 +15,8 @@
   "plugins": [
     "flowtype",
     "import",
-    "jsdoc"
+    "jsdoc",
+    "eslint-plugin-jsdoc"
   ],
   "rules": {
     // no-duplicate-imports doesn't play well with Flow
@@ -81,19 +82,25 @@
     "no-multiple-empty-lines": [ "error", {
         "max": 1
     }],
-    "jsdoc/check-param-names": "warn",
-    "jsdoc/require-param": "warn",
-    "jsdoc/require-param-description": "warn",
-    "jsdoc/require-param-name": "warn",
-    "jsdoc/require-returns": "warn",
-    "jsdoc/require-returns-description": "warn"
   },
   "settings": {
     "jsdoc":{
-      "ignorePrivate": true
+      "ignorePrivate": true,
+      "preferredTypes": {
+        "object": "Object"
+      }
     }
   },
   "overrides": [
+    {
+      "files": ["src/fake_filename_for_jsdoc_examples"],
+      "rules": {
+        "flowtype/require-valid-file-annotation": "off"
+      },
+      "globals": {
+        "map": true
+      }
+    },
     {
       "files": ["debug/**", "bench/**", "test/**", "src/style-spec/**"],
       "rules": {
@@ -103,7 +110,64 @@
         "jsdoc/require-param-description": "off",
         "jsdoc/require-param-name": "off",
         "jsdoc/require-returns": "off",
-        "jsdoc/require-returns-description": "off"
+        "jsdoc/require-returns-description": "off",
+        "jsdoc/require-property": "off",
+        "jsdoc/require-description-complete-sentence": "off",
+        "jsdoc/check-access": "off",
+        "jsdoc/check-examples": "off",
+        "jsdoc/check-line-alignment": "off",
+        "jsdoc/check-property-names": "off",
+        "jsdoc/check-types": "off",
+        "jsdoc/newline-after-description": "off",
+        "jsdoc/require-description": "off",
+        "jsdoc/require-example": "off",
+        "jsdoc/require-param-type": "off",
+        "jsdoc/require-property-description": "off",
+        "jsdoc/require-property-name": "off",
+        "jsdoc/require-property-type": "off",
+        "jsdoc/require-returns-type": "off",
+      }
+    },
+    {
+      "files": [
+        "src/index.js",
+        "src/ui/map.js",
+        "src/ui/camera.js",
+        "src/ui/marker.js",
+        "src/ui/popup.js",
+        "src/ui/events.js",
+        "src/ui/control/**",
+        "src/ui/handler/**",
+        "src/geo/lng_lat.js",
+        "src/geo/lng_lat_bounds.js",
+        "src/geo/mercator_coordinate.js",
+        "src/source/**",
+      ],
+      "rules": {
+        "jsdoc/check-param-names": "error",
+        "jsdoc/require-param": "error",
+        "jsdoc/require-param-description": "error",
+        "jsdoc/require-param-name": "error",
+        "jsdoc/require-returns": "error",
+        "jsdoc/require-returns-description": "error",
+        "jsdoc/require-property": "error",
+        "jsdoc/require-description-complete-sentence": "error",
+        "jsdoc/check-access": "error",
+        "jsdoc/check-examples": ["error", {
+            "matchingFileName": "src/fake_filename_for_jsdoc_examples",
+            "rejectExampleCodeRegex": "<script>"
+        }],
+        "jsdoc/check-line-alignment": "error",
+        "jsdoc/check-property-names": "error",
+        "jsdoc/check-types": "error",
+        "jsdoc/newline-after-description": "error",
+        "jsdoc/require-description": "error",
+        "jsdoc/require-example": "error",
+        "jsdoc/require-param-type": "error",
+        "jsdoc/require-property-description": "error",
+        "jsdoc/require-property-name": "error",
+        "jsdoc/require-property-type": "error",
+        "jsdoc/require-returns-type": "error",
       }
     }
   ],
@@ -114,4 +178,4 @@
     "es6": true,
     "browser": false
   }
-}
+}

README.md

@@ -32,6 +32,6 @@ Copyright © 2020 Mapbox
 
 All rights reserved.
 
-Mapbox GL-JS version 2.0 or higher (“Mapbox Web SDK”) must be used according to the Mapbox Terms of Service. This license allows developers with a current active Mapbox account to use and modify the Mapbox Web SDK. Developers may modify the Mapbox Web SDK code so long as the modifications do not change or interfere with marked portions of the code related to billing, accounting, and anonymized data collection. The Mapbox Web SDK sends only anonymized usage data, which Mapbox uses for fixing bugs and errors, accounting, and generating aggregated anonymized statistics. This license terminates automatically if a user no longer has an active Mapbox account.
+Mapbox GL JS version 2.0 or higher (“Mapbox Web SDK”) must be used according to the Mapbox Terms of Service. This license allows developers with a current active Mapbox account to use and modify the Mapbox Web SDK. Developers may modify the Mapbox Web SDK code so long as the modifications do not change or interfere with marked portions of the code related to billing, accounting, and anonymized data collection. The Mapbox Web SDK sends only anonymized usage data, which Mapbox uses for fixing bugs and errors, accounting, and generating aggregated anonymized statistics. This license terminates automatically if a user no longer has an active Mapbox account.
 
 For the full license terms, please see the [Mapbox Terms of Service](https://www.mapbox.com/legal/tos/).

package.json

@@ -63,12 +63,12 @@
     "diff": "^5.0.0",
     "documentation": "~13.1.1",
     "ejs": "^3.1.6",
-    "eslint": "^7.20.0",
+    "eslint": "^7.30.0",
     "eslint-config-mourner": "^3.0.0",
     "eslint-plugin-flowtype": "^5.2.0",
     "eslint-plugin-html": "^6.1.1",
     "eslint-plugin-import": "^2.22.1",
-    "eslint-plugin-jsdoc": "^32.0.0",
+    "eslint-plugin-jsdoc": "^32.3.4",
     "flow-bin": "^0.100.0",
     "gl": "^4.9.0",
     "glob": "^7.1.6",
@@ -134,9 +134,8 @@
     "diff-tarball": "build/run-node build/diff-tarball && echo \"Please confirm the above is correct [y/n]? \"; read answer; if [ \"$answer\" = \"${answer#[Yy]}\" ]; then false; fi",
     "prepare-publish": "git clean -fdx && yarn install",
     "lint": "eslint --cache --ignore-path .gitignore src test bench debug/*.html",
-    "lint-docs": "documentation lint src/index.js",
     "lint-css": "stylelint 'src/css/mapbox-gl.css'",
-    "test": "run-s lint lint-css lint-docs test-flow test-unit",
+    "test": "run-s lint lint-css test-flow test-unit",
     "test-suite": "run-s test-render test-query test-expressions",
     "test-suite-clean": "find test/integration/{render,query, expressions}-tests -mindepth 2 -type d -exec test -e \"{}/actual.png\" \\; -not \\( -exec test -e \"{}/style.json\" \\; \\) -print | xargs -t rm -r",
     "test-unit": "build/run-tap --reporter classic --no-coverage test/unit",

src/geo/edge_insets.js

@@ -39,6 +39,7 @@ class EdgeInsets {
      * Interpolates the inset in-place.
      * This maintains the current inset value for any inset not present in `target`.
      *
+     * @private
      * @param {PaddingOptions | EdgeInsets} start The initial padding options.
      * @param {PaddingOptions} target The target padding options.
      * @param {number} t The interpolation variable.
@@ -58,6 +59,7 @@ class EdgeInsets {
      * Utility method that computes the new apprent center or vanishing point after applying insets.
      * This is in pixels and with the top left being (0.0) and +y being downwards.
      *
+     * @private
      * @param {number} width The width of the map in pixels.
      * @param {number} height The height of the map in pixels.
      * @returns {Point} The apparent center or vanishing point of the map.
@@ -86,6 +88,7 @@ class EdgeInsets {
      * Returns the current state as json, useful when you want to have a
      * read-only representation of the inset.
      *
+     * @private
      * @returns {PaddingOptions} The current padding options.
      * @memberof EdgeInsets
      */

src/geo/lng_lat.js

@@ -24,8 +24,8 @@ export const earthRadius = 6371008.8;
  * @param {number} lng Longitude, measured in degrees.
  * @param {number} lat Latitude, measured in degrees.
  * @example
- * var ll = new mapboxgl.LngLat(-123.9749, 40.7736);
- * ll.lng; // = -123.9749
+ * const ll = new mapboxgl.LngLat(-123.9749, 40.7736);
+ * console.log(ll.lng); // = -123.9749
  * @see [Example: Get coordinates of the mouse pointer](https://www.mapbox.com/mapbox-gl-js/example/mouse-position/)
  * @see [Example: Display a popup](https://www.mapbox.com/mapbox-gl-js/example/popup/)
  * @see [Example: Highlight features within a bounding box](https://www.mapbox.com/mapbox-gl-js/example/using-box-queryrenderedfeatures/)
@@ -51,9 +51,9 @@ class LngLat {
      *
      * @returns {LngLat} The wrapped `LngLat` object.
      * @example
-     * var ll = new mapboxgl.LngLat(286.0251, 40.7736);
-     * var wrapped = ll.wrap();
-     * wrapped.lng; // = -73.9749
+     * const ll = new mapboxgl.LngLat(286.0251, 40.7736);
+     * const wrapped = ll.wrap();
+     * console.log(wrapped.lng); // = -73.9749
      */
     wrap() {
         return new LngLat(wrap(this.lng, -180, 180), this.lat);
@@ -64,7 +64,7 @@ class LngLat {
      *
      * @returns {Array<number>} The coordinates represeted as an array of longitude and latitude.
      * @example
-     * var ll = new mapboxgl.LngLat(-73.9749, 40.7736);
+     * const ll = new mapboxgl.LngLat(-73.9749, 40.7736);
      * ll.toArray(); // = [-73.9749, 40.7736]
      */
     toArray() {
@@ -76,23 +76,23 @@ class LngLat {
      *
      * @returns {string} The coordinates represented as a string of the format `'LngLat(lng, lat)'`.
      * @example
-     * var ll = new mapboxgl.LngLat(-73.9749, 40.7736);
+     * const ll = new mapboxgl.LngLat(-73.9749, 40.7736);
      * ll.toString(); // = "LngLat(-73.9749, 40.7736)"
      */
     toString() {
         return `LngLat(${this.lng}, ${this.lat})`;
     }
 
     /**
-     * Returns the approximate distance between a pair of coordinates in meters
-     * Uses the Haversine Formula (from R.W. Sinnott, "Virtues of the Haversine", Sky and Telescope, vol. 68, no. 2, 1984, p. 159)
+     * Returns the approximate distance between a pair of coordinates in meters.
+     * Uses the Haversine Formula (from R.W. Sinnott, "Virtues of the Haversine", Sky and Telescope, vol. 68, no. 2, 1984, p. 159).
      *
-     * @param {LngLat} lngLat coordinates to compute the distance to
+     * @param {LngLat} lngLat Coordinates to compute the distance to.
      * @returns {number} Distance in meters between the two coordinates.
      * @example
-     * var new_york = new mapboxgl.LngLat(-74.0060, 40.7128);
-     * var los_angeles = new mapboxgl.LngLat(-118.2437, 34.0522);
-     * new_york.distanceTo(los_angeles); // = 3935751.690893987, "true distance" using a non-spherical approximation is ~3966km
+     * const newYork = new mapboxgl.LngLat(-74.0060, 40.7128);
+     * const losAngeles = new mapboxgl.LngLat(-118.2437, 34.0522);
+     * newYork.distanceTo(losAngeles); // = 3935751.690893987, "true distance" using a non-spherical approximation is ~3966km
      */
     distanceTo(lngLat: LngLat) {
         const rad = Math.PI / 180;
@@ -110,7 +110,7 @@ class LngLat {
      * @param {number} [radius=0] Distance in meters from the coordinates to extend the bounds.
      * @returns {LngLatBounds} A new `LngLatBounds` object representing the coordinates extended by the `radius`.
      * @example
-     * var ll = new mapboxgl.LngLat(-73.9749, 40.7736);
+     * const ll = new mapboxgl.LngLat(-73.9749, 40.7736);
      * ll.toBounds(100).toArray(); // = [[-73.97501862141328, 40.77351016847229], [-73.97478137858673, 40.77368983152771]]
      */
     toBounds(radius?: number = 0) {
@@ -131,9 +131,9 @@ class LngLat {
      * @param {LngLatLike} input An array of two numbers or object to convert, or a `LngLat` object to return.
      * @returns {LngLat} A new `LngLat` object, if a conversion occurred, or the original `LngLat` object.
      * @example
-     * var arr = [-73.9749, 40.7736];
-     * var ll = mapboxgl.LngLat.convert(arr);
-     * ll;   // = LngLat {lng: -73.9749, lat: 40.7736}
+     * const arr = [-73.9749, 40.7736];
+     * const ll = mapboxgl.LngLat.convert(arr);
+     * console.log(ll);   // = LngLat {lng: -73.9749, lat: 40.7736}
      */
     static convert(input: LngLatLike): LngLat {
         if (input instanceof LngLat) {
@@ -159,9 +159,9 @@ class LngLat {
  *
  * @typedef {LngLat | {lng: number, lat: number} | {lon: number, lat: number} | [number, number]} LngLatLike
  * @example
- * var v1 = new mapboxgl.LngLat(-122.420679, 37.772537);
- * var v2 = [-122.420679, 37.772537];
- * var v3 = {lon: -122.420679, lat: 37.772537};
+ * const v1 = new mapboxgl.LngLat(-122.420679, 37.772537);
+ * const v2 = [-122.420679, 37.772537];
+ * const v3 = {lon: -122.420679, lat: 37.772537};
  */
 export type LngLatLike = LngLat | {lng: number, lat: number} | {lon: number, lat: number} | [number, number];