Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fix JSDoc lint warnings #10127

Merged
merged 2 commits into from
Jan 21, 2021
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 10 additions & 9 deletions src/geo/edge_insets.js
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ import {clamp} from "../util/util";

/**
* An `EdgeInset` object represents screen space padding applied to the edges of the viewport.
* This shifts the apprent center or the vanishing point of the map. This is useful for adding floating UI elements
* This shifts the apparent center or the vanishing point of the map. This is useful for adding floating UI elements
* on top of the map and having the vanishing point shift as UI elements resize.
*
* @param {number} [top=0]
Expand Down Expand Up @@ -38,9 +38,10 @@ class EdgeInsets {
* Interpolates the inset in-place.
* This maintains the current inset value for any inset not present in `target`.
*
* @param {PaddingOptions} target
* @param {number} t
* @returns {EdgeInsets}
* @param {PaddingOptions | EdgeInsets} start The initial padding options.
* @param {PaddingOptions} target The target padding options.
* @param {number} t The interpolation variable.
* @returns {EdgeInsets} The interpolated edge insets.
* @memberof EdgeInsets
*/
interpolate(start: PaddingOptions | EdgeInsets, target: PaddingOptions, t: number): EdgeInsets {
Expand All @@ -56,9 +57,9 @@ 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.
*
* @param {number} width
* @param {number} height
* @returns {Point}
* @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.
* @memberof EdgeInsets
*/
getCenter(width: number, height: number): Point {
Expand All @@ -81,10 +82,10 @@ class EdgeInsets {
}

/**
* Returns the current sdtate as json, useful when you want to have a
* Returns the current state as json, useful when you want to have a
* read-only representation of the inset.
*
* @returns {PaddingOptions}
* @returns {PaddingOptions} The current padding options.
* @memberof EdgeInsets
*/
toJSON(): PaddingOptions {
Expand Down
29 changes: 16 additions & 13 deletions src/geo/transform.js
Original file line number Diff line number Diff line change
Expand Up @@ -331,7 +331,8 @@ class Transform {

/**
* Computes a zoom value relative to a map plane that goes through the provided mercator position.
* @param {*} position A position defining the altitude of the the map plane
* @param {MercatorCoordinate} position A position defining the altitude of the the map plane.
* @returns {number} The zoom value.
*/
computeZoomRelativeTo(position: MercatorCoordinate): number {
// Find map center position on the target plane by casting a ray from screen center towards the plane.
Expand Down Expand Up @@ -447,21 +448,22 @@ class Transform {
}

/**
* Returns if the padding params match
* Returns true if the padding options are equal.
*
* @param {PaddingOptions} padding
* @returns {boolean}
* @param {PaddingOptions} padding The padding options to compare.
* @returns {boolean} True if the padding options are equal.
* @memberof Transform
*/
isPaddingEqual(padding: PaddingOptions): boolean {
return this._edgeInsets.equals(padding);
}

/**
* Helper method to upadte edge-insets inplace
* Helper method to update edge-insets inplace.
*
* @param {PaddingOptions} target
* @param {number} t
* @param {PaddingOptions} start The initial padding options.
* @param {PaddingOptions} target The target padding options.
* @param {number} t The interpolation variable.
* @memberof Transform
*/
interpolatePadding(start: PaddingOptions, target: PaddingOptions, t: number) {
Expand Down Expand Up @@ -1224,9 +1226,9 @@ class Transform {

/**
* Returns the minimum zoom at which `this.width` can fit `this.lngRange`
* and `this.height` can fit `this.latRange`
* and `this.height` can fit `this.latRange`.
*
* @returns {number}
* @returns {number} The zoom value.
*/
_minZoomForBounds(): number {
const minZoomForDim = (dim: number, range: [number, number]): number => {
Expand All @@ -1251,7 +1253,7 @@ class Transform {
* `this.width` can fit `this.lngRange` and `this.height` can fit `this.latRange`.
* In mercator units.
*
* @returns {number}
* @returns {number} The mercator z coordinate.
*/
_maxCameraBoundsDistance(): number {
return this._mercatorZfromZoom(this._minZoomForBounds());
Expand Down Expand Up @@ -1389,7 +1391,7 @@ class Transform {
* Apply a 3d translation to the camera position, but clamping it so that
* it respects the bounds set by `this.latRange` and `this.lngRange`.
*
* @param {vec3} translation
* @param {vec3} translation The translation vector.
*/
_translateCameraConstrained(translation: vec3) {
const maxDistance = this._maxCameraBoundsDistance();
Expand Down Expand Up @@ -1508,9 +1510,10 @@ class Transform {
}

/**
* Converts a zoom delta value into a physical distance travelled in web mercator coordinates
* Converts a zoom delta value into a physical distance travelled in web mercator coordinates.
* @param {vec3} center Destination mercator point of the movement.
* @param {number} zoomDelta Change in the zoom value
* @param {number} zoomDelta Change in the zoom value.
* @returns {number} The distance in mercator coordinates.
*/
zoomDeltaToMovement(center: vec3, zoomDelta: number): number {
const distance = vec3.length(vec3.sub([], this._camera.position, center));
Expand Down
1 change: 1 addition & 0 deletions src/source/canvas_source.js
Original file line number Diff line number Diff line change
Expand Up @@ -173,6 +173,7 @@ class CanvasSource extends ImageSource {
* They do not have to represent a rectangle.
* @returns {CanvasSource} this
*/

// setCoordinates inherited from ImageSource

prepare() {
Expand Down
20 changes: 10 additions & 10 deletions src/style/query_geometry.js
Original file line number Diff line number Diff line change
Expand Up @@ -48,9 +48,9 @@ export class QueryGeometry {
* Factory method to help contruct an instance while accounting for current map state.
*
* @static
* @param {(PointLike | [PointLike, PointLike])} geometry
* @param {Transform} transform
* @returns {QueryGeometry}
* @param {(PointLike | [PointLike, PointLike])} geometry The query geometry.
* @param {Transform} transform The current map transform.
* @returns {QueryGeometry} An instance of the QueryGeometry class.
*/
static createFromScreenPoints(geometry: PointLike | [PointLike, PointLike], transform: Transform): QueryGeometry {
let screenGeometry;
Expand All @@ -76,8 +76,8 @@ export class QueryGeometry {
* Each tile calculates a tile level max padding value (in screenspace pixels) when its parsed, this function
* lets us calculate a buffered version of the screenspace query geometry for each tile.
*
* @param {number} buffer
* @returns {Point[]}
* @param {number} buffer The tile padding in screenspace pixels.
* @returns {Point[]} The buffered query geometry.
*/
bufferedScreenGeometry(buffer: number): Point[] {
return polygonizeBounds(
Expand All @@ -96,8 +96,8 @@ export class QueryGeometry {
* of the query frustum, and the top of the triangle being the point underneath the camera.
* Similar to `bufferedScreenGeometry`, buffering is added to account for variation in paint properties.
*
* @param {number} buffer
* @returns {Point[]}
* @param {number} buffer The tile padding in screenspace pixels.
* @returns {Point[]} The buffered query geometry.
*/
bufferedCameraGeometry(buffer: number): Point[] {
const cameraTriangle = [
Expand All @@ -112,9 +112,9 @@ export class QueryGeometry {
/**
* Checks if a tile is contained within this query geometry.
*
* @param {Tile} tile
* @param {Transform} transform
* @param {boolean} use3D
* @param {Tile} tile The tile to check.
* @param {Transform} transform The current map transform.
* @param {boolean} use3D A boolean indicating whether to query 3D features.
* @returns {?TilespaceQueryGeometry} Returns undefined if the tile does not intersect
*/
containsTile(tile: Tile, transform: Transform, use3D: boolean): ?TilespaceQueryGeometry {
Expand Down
6 changes: 5 additions & 1 deletion src/terrain/elevation.js
Original file line number Diff line number Diff line change
Expand Up @@ -81,7 +81,8 @@ export class Elevation {

/**
* Get elevation minimum and maximum for tile identified by `tileID`.
* @param {*} tileID is a sub tile (or covers the same space) of the DEM tile we read the information from.
* @param {OverscaledTileID} tileID is a sub tile (or covers the same space) of the DEM tile we read the information from.
* @returns {?{min: number, max: number}} The min and max elevation.
*/
getMinMaxForTile(tileID: OverscaledTileID): ?{min: number, max: number} {
const demTile = this.findDEMTileFor(tileID);
Expand All @@ -108,6 +109,9 @@ export class Elevation {
/**
* Performs raycast against visible DEM tiles on the screen and returns the distance travelled along the ray.
* x & y components of the position are expected to be in normalized mercator coordinates [0, 1] and z in meters.
* @param {vec3} position The ray origin.
* @param {vec3} dir The ray direction.
* @param {number} exaggeration The terrain exaggeration.
*/
raycast(position: vec3, dir: vec3, exaggeration: number): ?number {
throw new Error('Pure virtual method called.');
Expand Down
1 change: 1 addition & 0 deletions src/ui/map.js
Original file line number Diff line number Diff line change
Expand Up @@ -2151,6 +2151,7 @@ class Map extends Camera {
* @param {string} feature.source The id of the vector or GeoJSON source for the feature.
* @param {string} [feature.sourceLayer] (optional) *For vector tile sources, `sourceLayer` is required.*
* @param {Object} state A set of key-value pairs. The values should be valid JSON types.
* @returns {Map} The map object.
*
* @example
* // When the mouse moves over the `my-layer` layer, update
Expand Down
3 changes: 2 additions & 1 deletion src/util/browser.js
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,8 @@ let stubTime;
*/
const exported = {
/**
* Returns either performance.now() or a value set by setNow
* Returns either performance.now() or a value set by setNow.
* @returns Time value in milliseconds.
*/
now(): number {
if (stubTime !== undefined) {
Expand Down
16 changes: 8 additions & 8 deletions src/util/util.js
Original file line number Diff line number Diff line change
Expand Up @@ -90,10 +90,10 @@ export function getBounds(points: Point[]): { min: Point, max: Point} {
/**
* Converts a AABB into a closed polygon with clockwise winding order.
*
* @param {Point} min
* @param {Point} max
* @param {number} [buffer=0]
* @returns {Point[]}
* @param {Point} min The top left point.
* @param {Point} max The bottom right point.
* @param {number} [buffer=0] The buffer width.
* @returns {Point[]} The polygon.
*/
export function polygonizeBounds(min: Point, max: Point, buffer: number = 0): Point[] {
const offset = new Point(buffer, buffer);
Expand All @@ -103,12 +103,12 @@ export function polygonizeBounds(min: Point, max: Point, buffer: number = 0): Po
}

/**
* Takes a convex ring and applies and expands it outward by applying a buffer around it.
* Takes a convex ring and expands it outward by applying a buffer around it.
* This function assumes that the ring is in clockwise winding order.
*
* @param {Point[]} ring
* @param {number} buffer
* @returns {Point[]}
* @param {Point[]} ring The input ring.
* @param {number} buffer The buffer width.
* @returns {Point[]} The expanded ring.
*/
export function bufferConvexPolygon(ring: Point[], buffer: number): Point[] {
assert(ring.length > 2, 'bufferConvexPolygon requires the ring to have atleast 3 points');
Expand Down