Eslint JSDoc fixes (mapbox#8960)

* add eslint jsdoc rules only

* begin updating JSDoc to satisfy eslint requirements

* address new linting warnings

* Update src/source/image_source.js

* Update src/ui/map.js

* lowercase boolean

* address jsdoc feedback

* revert changes to yarn.lock

src/data/array_types.js

@@ -859,6 +859,7 @@ export class CollisionBoxArray extends StructArrayLayout6i1ul2ui2i24 {
     /**
      * Return the CollisionBoxStruct at the given location in the array.
      * @param {number} index The index of the element.
+     * @private
      */
     get(index: number): CollisionBoxStruct {
         assert(!this.isTransferred);
@@ -934,6 +935,7 @@ export class PlacedSymbolArray extends StructArrayLayout2i2ui3ul3ui2f3ub1ul1i48
     /**
      * Return the PlacedSymbolStruct at the given location in the array.
      * @param {number} index The index of the element.
+     * @private
      */
     get(index: number): PlacedSymbolStruct {
         assert(!this.isTransferred);
@@ -1036,6 +1038,7 @@ export class SymbolInstanceArray extends StructArrayLayout8i14ui1ul3f60 {
     /**
      * Return the SymbolInstanceStruct at the given location in the array.
      * @param {number} index The index of the element.
+     * @private
      */
     get(index: number): SymbolInstanceStruct {
         assert(!this.isTransferred);
@@ -1064,6 +1067,7 @@ export class GlyphOffsetArray extends StructArrayLayout1f4 {
     /**
      * Return the GlyphOffsetStruct at the given location in the array.
      * @param {number} index The index of the element.
+     * @private
      */
     get(index: number): GlyphOffsetStruct {
         assert(!this.isTransferred);
@@ -1100,6 +1104,7 @@ export class SymbolLineVertexArray extends StructArrayLayout3i6 {
     /**
      * Return the SymbolLineVertexStruct at the given location in the array.
      * @param {number} index The index of the element.
+     * @private
      */
     get(index: number): SymbolLineVertexStruct {
         assert(!this.isTransferred);
@@ -1133,6 +1138,7 @@ export class FeatureIndexArray extends StructArrayLayout1ul2ui8 {
     /**
      * Return the FeatureIndexStruct at the given location in the array.
      * @param {number} index The index of the element.
+     * @private
      */
     get(index: number): FeatureIndexStruct {
         assert(!this.isTransferred);

src/geo/lng_lat_bounds.js

@@ -41,7 +41,7 @@ class LngLatBounds {
     /**
      * Set the northeast corner of the bounding box
      *
-     * @param {LngLatLike} ne
+     * @param {LngLatLike} ne a {@link LngLatLike} object describing the northeast corner of the bounding box.
      * @returns {LngLatBounds} `this`
      */
     setNorthEast(ne: LngLatLike) {
@@ -52,7 +52,7 @@ class LngLatBounds {
     /**
      * Set the southwest corner of the bounding box
      *
-     * @param {LngLatLike} sw
+     * @param {LngLatLike} sw a {@link LngLatLike} object describing the southwest corner of the bounding box.
      * @returns {LngLatBounds} `this`
      */
     setSouthWest(sw: LngLatLike) {

src/geo/transform.js

@@ -257,10 +257,10 @@ class Transform {
 
     /**
      * Return a zoom level that will cover all tiles the transform
-     * @param {Object} options
-     * @param {number} options.tileSize
-     * @param {boolean} options.roundZoom
-     * @returns {number} zoom level
+     * @param {Object} options options
+     * @param {number} options.tileSize Tile size, expressed in screen pixels.
+     * @param {boolean} options.roundZoom Target zoom level. If true, the value will be rounded to the closest integer. Otherwise the value will be floored.
+     * @returns {number} zoom level An integer zoom level at which all tiles will be visible.
      */
     coveringZoomLevel(options: {roundZoom?: boolean, tileSize: number}) {
         const z = (options.roundZoom ? Math.round : Math.floor)(
@@ -310,6 +310,7 @@ class Transform {
      * @param {boolean} options.reparseOverscaled
      * @param {boolean} options.renderWorldCopies
      * @returns {Array<OverscaledTileID>} OverscaledTileIDs
+     * @private
      */
     coveringTiles(
         options: {
@@ -460,6 +461,7 @@ class Transform {
      * Given a location, return the screen point that corresponds to it
      * @param {LngLat} lnglat location
      * @returns {Point} screen point
+     * @private
      */
     locationPoint(lnglat: LngLat) {
         return this.coordinatePoint(this.locationCoordinate(lnglat));
@@ -469,6 +471,7 @@ class Transform {
      * Given a point on screen, return its lnglat
      * @param {Point} p screen point
      * @returns {LngLat} lnglat location
+     * @private
      */
     pointLocation(p: Point) {
         return this.coordinateLocation(this.pointCoordinate(p));
@@ -479,6 +482,7 @@ class Transform {
      * coordinate that represents it at this transform's zoom level.
      * @param {LngLat} lnglat
      * @returns {Coordinate}
+     * @private
      */
     locationCoordinate(lnglat: LngLat) {
         return MercatorCoordinate.fromLngLat(lnglat);
@@ -488,6 +492,7 @@ class Transform {
      * Given a Coordinate, return its geographical position.
      * @param {Coordinate} coord
      * @returns {LngLat} lnglat
+     * @private
      */
     coordinateLocation(coord: MercatorCoordinate) {
         return coord.toLngLat();
@@ -525,6 +530,7 @@ class Transform {
      * Given a coordinate, return the screen point that corresponds to it
      * @param {Coordinate} coord
      * @returns {Point} screen point
+     * @private
      */
     coordinatePoint(coord: MercatorCoordinate) {
         const p = [coord.x * this.worldSize, coord.y * this.worldSize, 0, 1];
@@ -535,6 +541,7 @@ class Transform {
     /**
      * Returns the map's geographical bounds. When the bearing or pitch is non-zero, the visible region is not
      * an axis-aligned rectangle, and the result is the smallest bounds that encompasses the visible region.
+     * @returns {LngLatBounds} Returns a {@link LngLatBounds} object describing the map's geographical bounds.
      */
     getBounds(): LngLatBounds {
         return new LngLatBounds()
@@ -546,6 +553,7 @@ class Transform {
 
     /**
      * Returns the maximum geographical bounds the map is constrained to, or `null` if none set.
+     * @returns {LngLatBounds} {@link LngLatBounds}
      */
     getMaxBounds(): LngLatBounds | null {
         if (!this.latRange || this.latRange.length !== 2 ||
@@ -556,6 +564,7 @@ class Transform {
 
     /**
      * Sets or clears the map's geographical constraints.
+     * @param {LngLatBounds} bounds A {@link LngLatBounds} object describing the new geographic boundaries of the map.
      */
     setMaxBounds(bounds?: LngLatBounds) {
         if (bounds) {
@@ -571,6 +580,7 @@ class Transform {
     /**
      * Calculate the posMatrix that, given a tile coordinate, would be used to display the tile on a map.
      * @param {UnwrappedTileID} unwrappedTileID;
+     * @private
      */
     calculatePosMatrix(unwrappedTileID: UnwrappedTileID, aligned: boolean = false): Float32Array {
         const posMatrixKey = unwrappedTileID.key;

src/gl/vertex_buffer.js

@@ -40,6 +40,7 @@ class VertexBuffer {
 
     /**
      * @param dynamicDraw Whether this buffer will be repeatedly updated.
+     * @private
      */
     constructor(context: Context, array: StructArray, attributes: $ReadOnlyArray<StructArrayMember>, dynamicDraw?: boolean) {
         this.length = array.length;

src/index.js

@@ -51,6 +51,7 @@ const exported = {
      * Gets and sets the map's [access token](https://www.mapbox.com/help/define-access-token/).
      *
      * @var {string} accessToken
+     * @returns {string} The currently set access token.
      * @example
      * mapboxgl.accessToken = myAccessToken;
      * @see [Display a map](https://www.mapbox.com/mapbox-gl-js/examples/)
@@ -67,6 +68,7 @@ const exported = {
      * Gets and sets the map's default API URL for requesting tiles, styles, sprites, and glyphs
      *
      * @var {string} baseApiUrl
+     * @returns {string} The current base API URL.
      * @example
      * mapboxgl.baseApiUrl = 'https://api.mapbox.com';
      */
@@ -84,6 +86,7 @@ const exported = {
      * Make sure to set this property before creating any map instances for it to have effect.
      *
      * @var {string} workerCount
+     * @returns {number} Number of workers currently configured.
      * @example
      * mapboxgl.workerCount = 2;
      */
@@ -100,6 +103,7 @@ const exported = {
      * which affects performance in raster-heavy maps. 16 by default.
      *
      * @var {string} maxParallelImageRequests
+     * @returns {number} Number of parallel requests currently configured.
      * @example
      * mapboxgl.maxParallelImageRequests = 10;
      */

src/render/painter.js

@@ -548,6 +548,7 @@ class Painter {
      * Transform a matrix to incorporate the *-translate and *-translate-anchor properties into it.
      * @param inViewportPixelUnitsUnits True when the units accepted by the matrix are in viewport pixels instead of tile units.
      * @returns {Float32Array} matrix
+     * @private
      */
     translatePosMatrix(matrix: Float32Array, tile: Tile, translate: [number, number], translateAnchor: 'map' | 'viewport', inViewportPixelUnitsUnits?: boolean) {
         if (!translate[0] && !translate[1]) return matrix;
@@ -594,6 +595,7 @@ class Painter {
      * Checks whether a pattern image is needed, and if it is, whether it is not loaded.
      *
      * @returns true if a needed image is missing and rendering needs to be skipped.
+     * @private
      */
     isPatternMissing(image: ?CrossFaded<ResolvedImage>): boolean {
         if (!image) return false;

src/source/geojson_worker_source.js

@@ -103,6 +103,7 @@ class GeoJSONWorkerSource extends VectorTileWorkerSource {
      * @param [loadGeoJSON] Optional method for custom loading/parsing of
      * GeoJSON based on parameters passed from the main-thread Source.
      * See {@link GeoJSONWorkerSource#loadGeoJSON}.
+     * @private
      */
     constructor(actor: Actor, layerIndex: StyleLayerIndex, availableImages: Array<string>, loadGeoJSON: ?LoadGeoJSON) {
         super(actor, layerIndex, availableImages, loadGeoJSONTile);
@@ -126,6 +127,7 @@ class GeoJSONWorkerSource extends VectorTileWorkerSource {
      *
      * @param params
      * @param callback
+     * @private
      */
     loadData(params: LoadGeoJSONParameters, callback: Callback<{
         resourceTiming?: {[_: string]: Array<PerformanceResourceTiming>},
@@ -233,6 +235,7 @@ class GeoJSONWorkerSource extends VectorTileWorkerSource {
     *
     * @param params
     * @param params.uid The UID for this tile.
+    * @private
     */
     reloadTile(params: WorkerTileParameters, callback: WorkerTileCallback) {
         const loaded = this.loaded,
@@ -255,6 +258,7 @@ class GeoJSONWorkerSource extends VectorTileWorkerSource {
      * @param params
      * @param [params.url] A URL to the remote GeoJSON data.
      * @param [params.data] Literal GeoJSON data. Must be provided if `params.url` is not.
+     * @private
      */
     loadGeoJSON(params: LoadGeoJSONParameters, callback: ResponseCallback<Object>) {
         // Because of same origin issues, urls must either include an explicit

src/source/image_source.js

@@ -137,7 +137,7 @@ class ImageSource extends Evented implements Source {
      * Updates the image URL and, optionally, the coordinates. To avoid having the image flash after changing,
      * set the `raster-fade-duration` paint property on the raster layer to 0.
      *
-     * @param {Object} options
+     * @param {Object} options Options object.
      * @param {string} [options.url] Required image URL.
      * @param {Array<Array<number>>} [options.coordinates] Four geographical coordinates,
      *   represented as arrays of longitude and latitude numbers, which define the corners of the image.

src/source/source_cache.js

@@ -117,6 +117,7 @@ class SourceCache extends Evented {
     /**
      * Return true if no tile data is pending, tiles will not change unless
      * an additional API call is received.
+     * @private
      */
     loaded(): boolean {
         if (this._sourceErrored) { return true; }
@@ -180,6 +181,7 @@ class SourceCache extends Evented {
 
     /**
      * Return all tile ids ordered with z-order, and cast to numbers
+     * @private
      */
     getIds(): Array<string> {
         return (values(this._tiles): any).map((tile: Tile) => tile.tileID).sort(compareTileId).map(id => id.key);
@@ -307,13 +309,15 @@ class SourceCache extends Evented {
     }
     /**
      * Get a specific tile by TileID
+     * @private
      */
     getTile(tileID: OverscaledTileID): Tile {
         return this.getTileByID(tileID.key);
     }
 
     /**
      * Get a specific tile by id
+     * @private
      */
     getTileByID(id: string): Tile {
         return this._tiles[id];
@@ -322,6 +326,7 @@ class SourceCache extends Evented {
     /**
      * For a given set of tiles, retain children that are loaded and have a zoom
      * between `zoom` (exclusive) and `maxCoveringZoom` (inclusive)
+     * @private
      */
     _retainLoadedChildren(
         idealTiles: {[_: any]: OverscaledTileID},
@@ -367,6 +372,7 @@ class SourceCache extends Evented {
 
     /**
      * Find a loaded parent of the given tile (up to minCoveringZoom)
+     * @private
      */
     findLoadedParent(tileID: OverscaledTileID, minCoveringZoom: number): ?Tile {
         if (tileID.key in this._loadedParentTiles) {
@@ -403,6 +409,7 @@ class SourceCache extends Evented {
      * Larger viewports use more tiles and need larger caches. Larger viewports
      * are more likely to be found on devices with more memory and on pages where
      * the map is more important.
+     * @private
      */
     updateCacheSize(transform: Transform) {
         const widthInTiles = Math.ceil(transform.width / this._source.tileSize) + 1;
@@ -462,6 +469,7 @@ class SourceCache extends Evented {
     /**
      * Removes tiles that are outside the viewport and adds new tiles that
      * are inside the viewport.
+     * @private
      */
     update(transform: Transform) {
         this.transform = transform;
@@ -783,6 +791,7 @@ class SourceCache extends Evented {
      * cover the given bounds.
      * @param pointQueryGeometry coordinates of the corners of bounding rectangle
      * @returns {Array<Object>} result items have {tile, minX, maxX, minY, maxY}, where min/max bounding values are the given bounds transformed in into the coordinate space of this tile.
+     * @private
      */
     tilesIn(pointQueryGeometry: Array<Point>, maxPitchScaleFactor: number, has3DLayer: boolean) {
 
@@ -901,6 +910,7 @@ class SourceCache extends Evented {
     /**
      * Sets the set of keys that the tile depends on. This allows tiles to
      * be reloaded when their dependencies change.
+     * @private
      */
     setDependencies(tileKey: string, namespace: string, dependencies: Array<string>) {
         const tile = this._tiles[tileKey];
@@ -911,6 +921,7 @@ class SourceCache extends Evented {
 
     /**
      * Reloads all tiles that depend on the given keys.
+     * @private
      */
     reloadTilesForDependencies(namespaces: Array<string>, keys: Array<string>) {
         for (const id in this._tiles) {

src/source/tile.js

@@ -91,6 +91,7 @@ class Tile {
     /**
      * @param {OverscaledTileID} tileID
      * @param size
+     * @private
      */
     constructor(tileID: OverscaledTileID, size: number) {
         this.tileID = tileID;

src/source/tile_cache.js

@@ -191,6 +191,8 @@ class TileCache {
     /**
      * Remove entries that do not pass a filter function. Used for removing
      * stale tiles from the cache.
+     *
+     * @param {function} filterFn Determines whether the tile is filtered. If the supplied function returns false, the tile will be filtered out.
      */
     filter(filterFn: (tile: Tile) => boolean) {
         const removed = [];