Resolves eslint-plugin-jsdoc test failures

.eslintrc

@@ -90,7 +90,7 @@
     "jsdoc/require-returns-description": "error",
     "jsdoc/require-property": "warn",
     "jsdoc/require-description-complete-sentence": "warn",
-    "jsdoc/check-access": "warn",
+    "jsdoc/check-access": "error",
     "jsdoc/check-alignment": "warn",
     "jsdoc/check-examples": ["error", {
         "matchingFileName": "src/fake_filename_for_jsdoc_examples",
@@ -103,13 +103,13 @@
     "jsdoc/check-types": "warn",
     "jsdoc/newline-after-description": "warn",
     "jsdoc/no-bad-blocks": "warn",
-    "jsdoc/require-description": "warn",
+    "jsdoc/require-description": "error",
     "jsdoc/require-example": "warn",
     "jsdoc/require-param-type": "warn",
     "jsdoc/require-property-description": "warn",
     "jsdoc/require-property-name": "warn",
     "jsdoc/require-property-type": "warn",
-    "jsdoc/require-returns-type": "warn",
+    "jsdoc/require-returns-type": "error",
     "jsdoc/require-throws": "warn",
     "jsdoc/valid-types": "warn"
   },

src/style/style.js

@@ -853,7 +853,7 @@ class Style extends Evented {
     /**
      * Moves a layer to a different z-position. The layer will be inserted before the layer with
      * ID `before`, or appended if `before` is omitted.
-     * @param {string} id  ID of the layer to move
+     * @param {string} id ID of the layer to move
      * @param {string} [before] ID of an existing layer to insert before
      */
     moveLayer(id: string, before?: string) {

src/ui/camera.js

@@ -162,7 +162,7 @@ class Camera extends Evented {
      * Returns the map's geographical centerpoint.
      *
      * @memberof Map#
-     * @returns The map's geographical centerpoint.
+     * @returns {LngLatLike} The map's geographical centerpoint.
      * @example
      * // return a LngLat object such as {lng: 0, lat: 0}
      * const center = map.getCenter();
@@ -232,7 +232,7 @@ class Camera extends Evented {
      * Returns the map's current zoom level.
      *
      * @memberof Map#
-     * @returns The map's current zoom level.
+     * @returns {number} The map's current zoom level.
      * @example
      * map.getZoom();
      */
@@ -338,7 +338,7 @@ class Camera extends Evented {
      * of 90° orients the map so that east is up.
      *
      * @memberof Map#
-     * @returns The map's current bearing.
+     * @returns {number} The map's current bearing.
      * @see [Navigate the map with game-like controls](https://www.mapbox.com/mapbox-gl-js/example/game-controls/)
      */
     getBearing(): number { return this.transform.bearing; }
@@ -356,7 +356,7 @@ class Camera extends Evented {
      * @fires moveend
      * @returns {Map} `this`
      * @example
-     * // rotate the map to 90 degrees
+     * // Rotate the map to 90 degrees.
      * map.setBearing(90);
      */
     setBearing(bearing: number, eventData?: Object) {
@@ -368,7 +368,7 @@ class Camera extends Evented {
      * Returns the current padding applied around the map viewport.
      *
      * @memberof Map#
-     * @returns The current padding around the map viewport.
+     * @returns {PaddingOptions} The current padding around the map viewport.
      */
     getPadding(): PaddingOptions { return this.transform.padding; }
 
@@ -463,15 +463,15 @@ class Camera extends Evented {
     }
 
     /**
-     * Returns the map's current pitch (tilt).
+     * Returns the map's current [pitch](https://docs.mapbox.com/help/glossary/camera/) (tilt).
      *
      * @memberof Map#
-     * @returns The map's current pitch, measured in degrees away from the plane of the screen.
+     * @returns {number} The map's current pitch, measured in degrees away from the plane of the screen.
      */
     getPitch(): number { return this.transform.pitch; }
 
     /**
-     * Sets the map's pitch (tilt). Equivalent to `jumpTo({pitch: pitch})`.
+     * Sets the map's [pitch](https://docs.mapbox.com/help/glossary/camera/) (tilt). Equivalent to `jumpTo({pitch: pitch})`.
      *
      * @memberof Map#
      * @param pitch The pitch to set, measured in degrees away from the plane of the screen (0-60).
@@ -487,6 +487,9 @@ class Camera extends Evented {
     }
 
     /**
+     * Returns a {@link CameraOptions} object for the highest zoom level
+     * up to and including `Map#getMaxZoom()` that fits the bounds
+     * in the viewport at the specified bearing.
      * @memberof Map#
      * @param {LngLatBoundsLike} bounds Calculate the center for these bounds in the viewport and use
      *      the highest zoom level up to and including `Map#getMaxZoom()` that fits

src/ui/events.js

@@ -13,7 +13,7 @@ import type LngLat from '../geo/lng_lat.js';
  * `MapMouseEvent` is a class used by other classes to generate
  * mouse events of specific types such as 'click' or 'hover'.
  * For a full list of available events, see [`Map` events](/mapbox-gl-js/api/map/#map-events).
- * @extends {Object}
+ * @extends Object
  * @example
  * // Example of a MapMouseEvent of type "click"
  * map.on('click', (e) => {
@@ -136,7 +136,7 @@ export class MapMouseEvent extends Event {
  * `MapTouchEvent` is a class used by other classes to generate
  * mouse events of specific types such as 'touchstart' or 'touchend'.
  * For a full list of available events, see [`Map` events](/mapbox-gl-js/api/map/#map-events).
- * @extends {Object}
+ * @extends Object
  * @example
  * // Example of a MapTouchEvent of type "touch"
  * map.on('touchstart', (e) => {
@@ -279,7 +279,7 @@ export class MapTouchEvent extends Event {
  * `MapWheelEvent` is a class used by other classes to generate
  * mouse events of specific types such as 'wheel'.
  * For a full list of available events, see [`Map` events](/mapbox-gl-js/api/map/#map-events).
- * @extends {Object}
+ * @extends Object
  * @example
  * // Example of a MapWheelEvent of type "wheel"
  * map.on('wheel', (e) => {

src/ui/map.js

@@ -235,24 +235,24 @@ const defaultOptions = {
  * @param {boolean} [options.doubleClickZoom=true] If `true`, the "double click to zoom" interaction is enabled (see {@link DoubleClickZoomHandler}).
  * @param {boolean|Object} [options.touchZoomRotate=true] If `true`, the "pinch to rotate and zoom" interaction is enabled. An `Object` value is passed as options to {@link TouchZoomRotateHandler#enable}.
  * @param {boolean|Object} [options.touchPitch=true] If `true`, the "drag to pitch" interaction is enabled. An `Object` value is passed as options to {@link TouchPitchHandler#enable}.
- * @param {boolean} [options.trackResize=true]  If `true`, the map will automatically resize when the browser window resizes.
+ * @param {boolean} [options.trackResize=true] If `true`, the map will automatically resize when the browser window resizes.
  * @param {LngLatLike} [options.center=[0, 0]] The inital geographical centerpoint of the map. If `center` is not specified in the constructor options, Mapbox GL JS will look for it in the map's style object. If it is not specified in the style, either, it will default to `[0, 0]` Note: Mapbox GL uses longitude, latitude coordinate order (as opposed to latitude, longitude) to match GeoJSON.
  * @param {number} [options.zoom=0] The initial zoom level of the map. If `zoom` is not specified in the constructor options, Mapbox GL JS will look for it in the map's style object. If it is not specified in the style, either, it will default to `0`.
  * @param {number} [options.bearing=0] The initial bearing (rotation) of the map, measured in degrees counter-clockwise from north. If `bearing` is not specified in the constructor options, Mapbox GL JS will look for it in the map's style object. If it is not specified in the style, either, it will default to `0`.
  * @param {number} [options.pitch=0] The initial pitch (tilt) of the map, measured in degrees away from the plane of the screen (0-85). If `pitch` is not specified in the constructor options, Mapbox GL JS will look for it in the map's style object. If it is not specified in the style, either, it will default to `0`.
  * @param {LngLatBoundsLike} [options.bounds] The initial bounds of the map. If `bounds` is specified, it overrides `center` and `zoom` constructor options.
  * @param {Object} [options.fitBoundsOptions] A {@link Map#fitBounds} options object to use _only_ when fitting the initial `bounds` provided above.
  * @param {boolean} [options.optimizeForTerrain=true] With terrain on, if `true`, the map will render for performance priority, which may lead to layer reordering allowing to maximize performance (layers that are draped over terrain will be drawn first, including fill, line, background, hillshade and raster). Otherwise, if set to `false`, the map will always be drawn for layer order priority.
- * @param {boolean} [options.renderWorldCopies=true]  If `true`, multiple copies of the world will be rendered side by side beyond -180 and 180 degrees longitude. If set to `false`:
+ * @param {boolean} [options.renderWorldCopies=true] If `true`, multiple copies of the world will be rendered side by side beyond -180 and 180 degrees longitude. If set to `false`:
  * - When the map is zoomed out far enough that a single representation of the world does not fill the map's entire
  * container, there will be blank space beyond 180 and -180 degrees longitude.
  * - Features that cross 180 and -180 degrees longitude will be cut in two (with one portion on the right edge of the
  * map and the other on the left edge of the map) at every zoom level.
- * @param {number} [options.maxTileCacheSize=null]  The maximum number of tiles stored in the tile cache for a given source. If omitted, the cache will be dynamically sized based on the current viewport.
+ * @param {number} [options.maxTileCacheSize=null] The maximum number of tiles stored in the tile cache for a given source. If omitted, the cache will be dynamically sized based on the current viewport.
  * @param {string} [options.localIdeographFontFamily='sans-serif'] Defines a CSS
  *   font-family for locally overriding generation of glyphs in the 'CJK Unified Ideographs', 'Hiragana', 'Katakana', 'Hangul Syllables' and 'CJK Symbols and Punctuation' ranges.
  *   In these ranges, font settings from the map's style will be ignored, except for font-weight keywords (light/regular/medium/bold).
- *   Set to `false`, to enable font settings from the map's style for these glyph ranges.  Note that [Mapbox Studio](https://studio.mapbox.com/) sets this value to `false` by default.
+ *   Set to `false`, to enable font settings from the map's style for these glyph ranges. Note that [Mapbox Studio](https://studio.mapbox.com/) sets this value to `false` by default.
  *   The purpose of this option is to avoid bandwidth-intensive glyph server requests. (See [Use locally generated ideographs](https://www.mapbox.com/mapbox-gl-js/example/local-ideographs).)
  * @param {string} [options.localFontFamily=false] Defines a CSS
  *   font-family for locally overriding generation of all glyphs. Font settings from the map's style will be ignored, except for font-weight keywords (light/regular/medium/bold).
@@ -677,7 +677,7 @@ class Map extends Camera {
 
     /**
      * Returns the maximum geographical bounds the map is constrained to, or `null` if none set.
-     * @returns The map object.
+     * @returns {Map} The map object.
      * @example
      * const maxBounds = map.getMaxBounds();
      */
@@ -1654,9 +1654,9 @@ class Map extends Camera {
      * @param options Options object.
      * @param options.pixelRatio The ratio of pixels in the image to physical pixels on the screen
      * @param options.sdf Whether the image should be interpreted as an SDF image
-     * @param options.content  `[x1, y1, x2, y2]`  If `icon-text-fit` is used in a layer with this image, this option defines the part of the image that can be covered by the content in `text-field`.
-     * @param options.stretchX  `[[x1, x2], ...]` If `icon-text-fit` is used in a layer with this image, this option defines the part(s) of the image that can be stretched horizontally.
-     * @param options.stretchY  `[[y1, y2], ...]` If `icon-text-fit` is used in a layer with this image, this option defines the part(s) of the image that can be stretched vertically.
+     * @param options.content `[x1, y1, x2, y2]` If `icon-text-fit` is used in a layer with this image, this option defines the part of the image that can be covered by the content in `text-field`.
+     * @param options.stretchX `[[x1, x2], ...]` If `icon-text-fit` is used in a layer with this image, this option defines the part(s) of the image that can be stretched horizontally.
+     * @param options.stretchY `[[y1, y2], ...]` If `icon-text-fit` is used in a layer with this image, this option defines the part(s) of the image that can be stretched vertically.
      *
      * @example
      * // If the style's sprite does not already contain an image with ID 'cat',
@@ -1770,7 +1770,7 @@ class Map extends Camera {
      *
      * @param id The ID of the image.
      *
-     * @returns {boolean}  A Boolean indicating whether the image exists.
+     * @returns {boolean} A Boolean indicating whether the image exists.
      * @example
      * // Check if an image with the ID 'cat' exists in
      * // the style's sprite.
@@ -3290,7 +3290,7 @@ function removeNode(node) {
  * A [`Point` geometry](https://github.com/mapbox/point-geometry) object, which has
  * `x` and `y` properties representing screen coordinates in pixels.
  *
- * @typedef {Object} Point
+ * @typedef {Point} Point
  * @example
  * const point = new mapboxgl.Point(-77, 38);
  */

src/ui/popup.js

@@ -183,6 +183,8 @@ export default class Popup extends Evented {
     }
 
     /**
+     * Checks if a popup is open.
+     *
      * @returns {boolean} `true` if the popup is open, `false` if it is closed.
      */
     isOpen() {

src/util/browser.js

@@ -15,7 +15,7 @@ let stubTime;
 const exported = {
     /**
      * Returns either performance.now() or a value set by setNow.
-     * @returns Time value in milliseconds.
+     * @returns {number} Time value in milliseconds.
      */
     now(): number {
         if (stubTime !== undefined) {
@@ -57,7 +57,7 @@ const exported = {
     get devicePixelRatio() { return window.devicePixelRatio; },
     get prefersReducedMotion(): boolean {
         if (!window.matchMedia) return false;
-        //Lazily initialize media query
+        // Lazily initialize media query.
         if (reducedMotionQuery == null) {
             reducedMotionQuery = window.matchMedia('(prefers-reduced-motion: reduce)');
         }

src/util/dispatcher.js

@@ -56,7 +56,7 @@ class Dispatcher {
 
     /**
      * Acquires an actor to dispatch messages to. The actors are distributed in round-robin fashion.
-     * @returns An actor object backed by a web worker for processing messages.
+     * @returns {Actor} An actor object backed by a web worker for processing messages.
      */
     getActor(): Actor {
         assert(this.actors.length);

src/util/evented.js

@@ -170,7 +170,6 @@ export class Evented {
     /**
      * Bubble all events fired by this instance of Evented to this parent instance of Evented.
      *
-     * @private
      * @returns {Object} `this`
      * @private
      */