Resolves eslint-plugin-jsdoc test failures (#10858)

* Adds 'resource type' prefix for related items in GL JS API docs (#10837) Co-authored-by: Asheem Mamoowala <asheem.mamoowala@mapbox.com> Co-authored-by: Heather Stenson <heather.stenson@mapbox.com> Co-authored-by: Karim Naaji <karim.naaji@gmail.com> Co-authored-by: Arindam Bose <arindam.bose@mapbox.com> Co-authored-by: Aidan H <aidan.hendrickson@mapbox.com>
mapbox · Jul 16, 2021 · f3253fb · f3253fb
1 parent 9a8445e
commit f3253fb
Show file tree

Hide file tree

Showing 32 changed files with 290 additions and 230 deletions.
diff --git a/.eslintrc b/.eslintrc
@@ -82,12 +82,6 @@
     "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":{
@@ -160,7 +154,7 @@
         "jsdoc/require-returns": "error",
         "jsdoc/require-returns-description": "error",
         "jsdoc/require-property": "warn",
-        "jsdoc/require-description-complete-sentence": "error",
+        "jsdoc/require-description-complete-sentence": "warn",
         "jsdoc/check-access": "warn",
         "jsdoc/check-alignment": "warn",
         "jsdoc/check-examples": ["error", {

diff --git a/src/geo/lng_lat.js b/src/geo/lng_lat.js
@@ -26,10 +26,10 @@ export const earthRadius = 6371008.8;
  * @example
  * const ll = new mapboxgl.LngLat(-123.9749, 40.7736);
  * console.log(ll.lng); // = -123.9749
- * @see [Get coordinates of the mouse pointer](https://www.mapbox.com/mapbox-gl-js/example/mouse-position/)
- * @see [Display a popup](https://www.mapbox.com/mapbox-gl-js/example/popup/)
- * @see [Highlight features within a bounding box](https://www.mapbox.com/mapbox-gl-js/example/using-box-queryrenderedfeatures/)
- * @see [Create a timeline animation](https://www.mapbox.com/mapbox-gl-js/example/timeline-animation/)
+ * @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/)
+ * @see [Example: Create a timeline animation](https://www.mapbox.com/mapbox-gl-js/example/timeline-animation/)
  */
 class LngLat {
     lng: number;

diff --git a/src/geo/mercator_coordinate.js b/src/geo/mercator_coordinate.js
@@ -74,7 +74,7 @@ export function mercatorScale(lat: number) {
  * @example
  * const nullIsland = new mapboxgl.MercatorCoordinate(0.5, 0.5, 0);
  *
- * @see [Add a custom style layer](https://www.mapbox.com/mapbox-gl-js/example/custom-style-layer/)
+ * @see [Example: Add a custom style layer](https://www.mapbox.com/mapbox-gl-js/example/custom-style-layer/)
  */
 class MercatorCoordinate {
     x: number;

diff --git a/src/index.js b/src/index.js
@@ -92,7 +92,7 @@ const exported = {
      * @returns {string} The currently set access token.
      * @example
      * mapboxgl.accessToken = myAccessToken;
-     * @see [Display a map](https://www.mapbox.com/mapbox-gl-js/examples/)
+     * @see [Example: Display a map](https://www.mapbox.com/mapbox-gl-js/example/simple-map/)
      */
     get accessToken(): ?string {
         return config.ACCESS_TOKEN;
@@ -248,7 +248,7 @@ Debug.extend(exported, {isSafari, getPerformanceMetrics: PerformanceUtils.getPer
  * if (!mapboxgl.supported()) {
  *     alert('Your browser does not support Mapbox GL');
  * }
- * @see [Check for browser support](https://www.mapbox.com/mapbox-gl-js/example/check-for-support/)
+ * @see [Example: Check for browser support](https://www.mapbox.com/mapbox-gl-js/example/check-for-support/)
  */
 
 /**
@@ -262,7 +262,7 @@ Debug.extend(exported, {isSafari, getPerformanceMetrics: PerformanceUtils.getPer
  *    rtl text will then be rendered only after the plugin finishes loading.
  * @example
  * mapboxgl.setRTLTextPlugin('https://api.mapbox.com/mapbox-gl-js/plugins/mapbox-gl-rtl-text/v0.2.0/mapbox-gl-rtl-text.js');
- * @see [Add support for right-to-left scripts](https://www.mapbox.com/mapbox-gl-js/example/mapbox-gl-rtl-text/)
+ * @see [Example: Add support for right-to-left scripts](https://www.mapbox.com/mapbox-gl-js/example/mapbox-gl-rtl-text/)
  */
 
 /**

diff --git a/src/source/canvas_source.js b/src/source/canvas_source.js
@@ -57,7 +57,7 @@ export type CanvasSourceSpecification = {|
  * ]);
  *
  * map.removeSource('some id');  // remove
- * @see [Add a canvas source](https://docs.mapbox.com/mapbox-gl-js/example/canvas-source/)
+ * @see [Example: Add a canvas source](https://docs.mapbox.com/mapbox-gl-js/example/canvas-source/)
  */
 class CanvasSource extends ImageSource {
     options: CanvasSourceSpecification;

diff --git a/src/source/geojson_source.js b/src/source/geojson_source.js
@@ -58,10 +58,10 @@ import type {Cancelable} from '../types/cancelable.js';
  *         }
  *     }]
  * });
- * @see [Draw GeoJSON points](https://www.mapbox.com/mapbox-gl-js/example/geojson-markers/)
- * @see [Add a GeoJSON line](https://www.mapbox.com/mapbox-gl-js/example/geojson-line/)
- * @see [Create a heatmap from points](https://www.mapbox.com/mapbox-gl-js/example/heatmap/)
- * @see [Create and style clusters](https://www.mapbox.com/mapbox-gl-js/example/cluster/)
+ * @see [Example: Draw GeoJSON points](https://www.mapbox.com/mapbox-gl-js/example/geojson-markers/)
+ * @see [Example: Add a GeoJSON line](https://www.mapbox.com/mapbox-gl-js/example/geojson-line/)
+ * @see [Example: Create a heatmap from points](https://www.mapbox.com/mapbox-gl-js/example/heatmap/)
+ * @see [Example: Create and style clusters](https://www.mapbox.com/mapbox-gl-js/example/cluster/)
  */
 class GeoJSONSource extends Evented implements Source {
     type: 'geojson';

diff --git a/src/source/image_source.js b/src/source/image_source.js
@@ -63,7 +63,7 @@ type Coordinates = [[number, number], [number, number], [number, number], [numbe
  * });
  *
  * map.removeSource('some id');  // remove
- * @see [Add an image](https://www.mapbox.com/mapbox-gl-js/example/image-on-a-map/)
+ * @see [Example: Add an image](https://www.mapbox.com/mapbox-gl-js/example/image-on-a-map/)
  */
 class ImageSource extends Evented implements Source {
     type: string;

diff --git a/src/source/vector_tile_source.js b/src/source/vector_tile_source.js
@@ -45,8 +45,8 @@ import type {LoadVectorTileResult} from './vector_tile_worker_source.js';
  *
  * @example
  * map.getSource('some id').setTiles(['https://d25uarhxywzl1j.cloudfront.net/v0.1/{z}/{x}/{y}.mvt']);
- * @see [Add a vector tile source](https://docs.mapbox.com/mapbox-gl-js/example/vector-source/)
- * @see [Add a third party vector tile source](https://docs.mapbox.com/mapbox-gl-js/example/third-party/)
+ * @see [Example: Add a vector tile source](https://docs.mapbox.com/mapbox-gl-js/example/vector-source/)
+ * @see [Example: Add a third party vector tile source](https://docs.mapbox.com/mapbox-gl-js/example/third-party/)
  */
 class VectorTileSource extends Evented implements Source {
     type: 'vector';

diff --git a/src/source/video_source.js b/src/source/video_source.js
@@ -44,7 +44,7 @@ import type {VideoSourceSpecification} from '../style-spec/types.js';
  * ]);
  *
  * map.removeSource('some id');  // remove
- * @see [Add a video](https://www.mapbox.com/mapbox-gl-js/example/video-on-a-map/)
+ * @see [Example: Add a video](https://www.mapbox.com/mapbox-gl-js/example/video-on-a-map/)
  */
 class VideoSource extends ImageSource {
     options: VideoSourceSpecification;

diff --git a/src/style-spec/reference/v8.json b/src/style-spec/reference/v8.json
@@ -616,7 +616,9 @@
           "doc": "A spherical dome around the map that is always rendered behind all other layers.",
           "sdk-support": {
             "basic functionality": {
-              "js": "2.0.0"
+              "js": "2.0.0",
+              "ios": "10.0.0",
+              "android": "10.0.0"
             }
           }
         }
@@ -712,7 +714,9 @@
       "doc": "Whether this layer is displayed.",
       "sdk-support": {
         "basic functionality": {
-          "js": "2.0.0"
+          "js": "2.0.0",
+          "ios": "10.0.0",
+          "android": "10.0.0"
         }
       },
       "property-type": "constant"
@@ -1831,7 +1835,12 @@
       "units": "ems",
       "doc": "The maximum line width for text wrapping.",
       "requires": [
-        "text-field"
+        "text-field",
+        {
+          "symbol-placement": [
+            "point"
+          ]
+        }
       ],
       "sdk-support": {
         "basic functionality": {
@@ -2966,7 +2975,10 @@
         "group": "Types",
         "sdk-support": {
           "basic functionality": {
-            "js": "0.54.0"
+            "js": "0.54.0",
+            "android" : "8.4.0",
+            "ios": "5.4.0",
+            "macos": "0.15.0"
           }
         }
       },
@@ -3112,7 +3124,7 @@
         }
       },
       "geometry-type": {
-        "doc": "Gets the feature's geometry type: `Point`, `MultiPoint`, `LineString`, `MultiLineString`, `Polygon`, `MultiPolygon`.",
+        "doc": "Gets the feature's geometry type: `Point`, `MultiPoint`, `LineString`, `MultiLineString`, `Polygon`, `MultiPolygon`. `Multi*` feature types are only returned in GeoJSON sources. When working with vector tile sources, use the singular forms.",
         "group": "Feature data",
         "sdk-support": {
           "basic functionality": {
@@ -3176,7 +3188,9 @@
         "group": "sky",
         "sdk-support": {
           "basic functionality": {
-            "js": "2.0.0"
+            "js": "2.0.0",
+            "ios": "10.0.0",
+            "android": "10.0.0"
           }
         }
       },
@@ -3185,7 +3199,10 @@
         "group": "Feature data",
         "sdk-support": {
           "basic functionality": {
-            "js": "0.53.0"
+            "js": "0.53.0",
+            "android": "8.4.0",
+            "ios": "5.5.0",
+            "macos": "0.15.0"
           }
         }
       },
@@ -3864,7 +3881,9 @@
       "required": true,
       "sdk-support": {
         "basic functionality": {
-          "js": "2.0.0"
+          "js": "2.0.0",
+          "ios": "10.0.0",
+          "android": "10.0.0"
         }
       }
     },
@@ -3884,7 +3903,9 @@
       "doc": "Exaggerates the elevation of the terrain by multiplying the data from the DEM with this value.",
       "sdk-support": {
         "basic functionality": {
-          "js": "2.0.0"
+          "js": "2.0.0",
+          "ios": "10.0.0",
+          "android": "10.0.0"
         }
       }
     }
@@ -4325,6 +4346,7 @@
       "sdk-support": {
         "basic functionality": {
           "js": "0.50.0",
+          "android": "7.0.0",
           "ios": "4.7.0",
           "macos": "0.13.0"
         }
@@ -6033,7 +6055,9 @@
       "doc": "The type of the sky",
       "sdk-support": {
         "basic functionality": {
-          "js": "2.0.0"
+          "js": "2.0.0",
+          "ios": "10.0.0",
+          "android": "10.0.0"
         }
       },
       "expression": {
@@ -6055,7 +6079,9 @@
       "doc": "Position of the sun center [a azimuthal angle, p polar angle]. The azimuthal angle indicates the position of the sun relative to 0° north, where degrees proceed clockwise. The polar angle indicates the height of the sun, where 0° is directly above, at zenith, and 90° at the horizon. When this property is ommitted, the sun center is directly inherited from the light position.",
       "sdk-support": {
         "basic functionality": {
-          "js": "2.0.0"
+          "js": "2.0.0",
+          "ios": "10.0.0",
+          "android": "10.0.0"
         }
       },
       "requires": [
@@ -6085,7 +6111,9 @@
       "doc": "Intensity of the sun as a light source in the atmosphere (on a scale from 0 to a 100). Setting higher values will brighten up the sky.",
       "sdk-support": {
         "basic functionality": {
-          "js": "2.0.0"
+          "js": "2.0.0",
+          "ios": "10.0.0",
+          "android": "10.0.0"
         }
       },
       "property-type": "data-constant"
@@ -6110,7 +6138,9 @@
       "doc": "Position of the gradient center [a azimuthal angle, p polar angle]. The azimuthal angle indicates the position of the gradient center relative to 0° north, where degrees proceed clockwise. The polar angle indicates the height of the gradient center, where 0° is directly above, at zenith, and 90° at the horizon.",
       "sdk-support": {
         "basic functionality": {
-          "js": "2.0.0"
+          "js": "2.0.0",
+          "ios": "10.0.0",
+          "android": "10.0.0"
         }
       },
       "expression": {
@@ -6135,7 +6165,9 @@
       "doc": "The angular distance (measured in degrees) from `sky-gradient-center` up to which the gradient extends. A value of 180 causes the gradient to wrap around to the opposite direction from `sky-gradient-center`.",
       "sdk-support": {
         "basic functionality": {
-          "js": "2.0.0"
+          "js": "2.0.0",
+          "ios": "10.0.0",
+          "android": "10.0.0"
         }
       },
       "expression": {
@@ -6170,7 +6202,9 @@
       ],
       "sdk-support": {
         "basic functionality": {
-          "js": "2.0.0"
+          "js": "2.0.0",
+          "ios": "10.0.0",
+          "android": "10.0.0"
         },
         "data-driven styling": {}
       },
@@ -6194,7 +6228,9 @@
       ],
       "sdk-support": {
         "basic functionality": {
-          "js": "2.0.0"
+          "js": "2.0.0",
+          "ios": "10.0.0",
+          "android": "10.0.0"
         }
       },
       "property-type": "data-constant"
@@ -6211,7 +6247,9 @@
       ],
       "sdk-support": {
         "basic functionality": {
-          "js": "2.0.0"
+          "js": "2.0.0",
+          "ios": "10.0.0",
+          "android": "10.0.0"
         }
       },
       "property-type": "data-constant"
@@ -6225,7 +6263,9 @@
       "transition": true,
       "sdk-support": {
         "basic functionality": {
-          "js": "2.0.0"
+          "js": "2.0.0",
+          "ios": "10.0.0",
+          "android": "10.0.0"
         }
       },
       "expression": {

diff --git a/src/style/style_image.js b/src/style/style_image.js
@@ -56,7 +56,7 @@ export function renderStyleImage(image: StyleImage) {
  * @property {number} height
  * @property {Uint8Array | Uint8ClampedArray} data
  *
- * @see [Add an animated icon to the map.](https://docs.mapbox.com/mapbox-gl-js/example/add-image-animated/)
+ * @see [Example: Add an animated icon to the map.](https://docs.mapbox.com/mapbox-gl-js/example/add-image-animated/)
  *
  * @example
  * const flashingSquare = {

diff --git a/src/style/style_layer/custom_style_layer.js b/src/style/style_layer/custom_style_layer.js
@@ -73,8 +73,8 @@ type CustomRenderMethod = (gl: WebGLRenderingContext, matrix: Array<number>) =>
  * map.on('load', () => {
  *     map.addLayer(new NullIslandLayer());
  * });
- * @see [Add a custom style layer](https://docs.mapbox.com/mapbox-gl-js/example/custom-style-layer/)
- * @see [Add a 3D model](https://docs.mapbox.com/mapbox-gl-js/example/add-3d-model/)
+ * @see [Example: Add a custom style layer](https://docs.mapbox.com/mapbox-gl-js/example/custom-style-layer/)
+ * @see [Example: Add a 3D model](https://docs.mapbox.com/mapbox-gl-js/example/add-3d-model/)
  */
 
 /**