Skip to content

Commit

Permalink
Documentation improvements sprint (#9607) (#9629)
Browse files Browse the repository at this point in the history 
Various documentation enhancements from the docs sprints:

* [docsprint] Clarify meaning of Map#isSourceLoaded (#9589)
* [docsprint] Add geolocate trigger example (#9552)
* [docsprint] Add inline snippet to marker#addTo (#9592)
* [docsprint] Add inline snippet and related examples to popup.setHTML (#9538)
* add inline snippet and related examples to popup.setHTML
* update see URLs to docs subdomain
* Add inline and related example for panTo (#9547)
* Add inline snippet to LngLatBounds.contains (#9548)
* [docsprint] Add inline snippet and examples to map.jumpTo (#9549)
* add inline snippet and examples to map.jumpTo
* minor reorder to match options and text
* added inline and tutorial examples for map.getCenter (#9551)
* add example for Marker class setLngLat (#9553)
* added examples to get- and setLayoutProperty (#9554)
* add inline snippet and examples to map.triggerRepaint (#9555)
* CameraOptions - update pitch and bearing definitions, add inline code example, add example links (#9556)
* add inline code snippet to map.showTileBoundaries (#9557)
* Mark Debug namespace as private to hide it from the docs (#9558)
* [docsprint] Add detail to docs on setFeatureState, removeFeatureState, getFeatureState (#9559)
* add detail to docs on setFeatureState, removeFeatureState, getFeatureState
* remove trailing spaces
* [docsprint] map.on: remove extra on section, link to event types, add code snippet, add related (#9560)
* add examples to open and close popup events (#9565)
* [docsprint] Clarify how map.moveLayer works (#9566)
* clarify how map.moveLayer works
* fix id capitalization
* [doscprint] add links to EPSG and minor example changes for LngLat (#9570)
* add links to EPSG and minor example changes for LngLat
* document the layer object's properties in addLayer (#9571)
* [docsprint] Add inline snippet and examples to popup.addTo (#9572)
* added inline example to popup-addto
* added relevant examples to popup.addto
* Add inline example for trackPointer (#9575)
* Add inline example for Popup#getElement (#9576)
* [docsprint] Add inline examples for Point & PointLike types (#9577)
* Add inline examples for Point & PointLike types
* Correct syntax
* [docsprint] Cleanup doc for MapBoxZoomEvent (#9564)
* Describe map style object returned by Map#getStyle (#9579)
* [docsprint] Add inline example for getClusterLeaves (#9580)
* [docsprint] PaddingOptions - update definition, example, and related (#9581)
* PaddingOptions - update definition, example, and related
* Fixes formatting issues
* [docsprint] Add inline snippet to marker#setPopup, marker#getPopup, and marker#togglePopup (#9582)
* update setPopup
* update togglePopup
* update formatting
* update setFilter jsdoc (#9586)
* add more details to getSource (#9587)
* add clearStorage example (#9588)
* [docsprint] Add documentation for RequestParameters (#9573)
* [docsprint] Add inline example for setZoomRate and setWheelZoomRate of scrollZoomHandler (#9593)
* Add inline example for setZoomRate of scrollZoomHandler
* add setWheelZoomRate inline example
* Add inline examples for map zoom-related methods (#9594)
* [docsprint] Add example to MapMouseEvent (#9595)
* add example to MapMouseEvent
* Add examples for GeolocateControl events (#9596)
* [docsprint] Add example to MapDataEvent (#9597)
* add example to MapDataEvent
* add example for getLngLat (#9591)
* suggested edits for clarifying mouse events
* Small grammar fix: "optional the `layerId`" -> "the optional `layerId"
* Update pitch param definition; add Display buildings in 3D example
* remove example object, light formatting and copyediting

# Conflicts:
#	src/ui/camera.js

Co-Authored-By: Dan Swick <dan.swick@gmail.com>
Co-authored-by: Adriana Babakanian <adriana.babakanian@mapbox.com>
Co-authored-by: Sam Fader <samfader@users.noreply.github.com>
Co-authored-by: Heather Stenson <heather.stenson@mapbox.com>
Co-authored-by: Katy DeCorah <decorah@mapbox.com>
Co-authored-by: jbranigan <john.branigan@mapbox.com>
Co-authored-by: Jeremy Stratman <jstratman@users.noreply.github.com>
Co-authored-by: Mal Wood-Santoro <mal.wood@mapbox.com>
Co-authored-by: Asheem Mamoowala <asheem.mamoowala@mapbox.com>
Co-authored-by: Colleen McGinnis <colleen.mcginnis@mapbox.com>
Co-authored-by: geografa <geografa@users.noreply.github.com>
Co-authored-by: Patrick Leonard <pjleonard37@users.noreply.github.com>
Co-authored-by: David Wicks <david.wicks@mapbox.com>
Co-authored-by: Deven Diliberto <deven.diliberto@mapbox.com>
Co-authored-by: Colleen <colleen.j.mcginnis@gmail.com>
Co-authored-by: Karim Naaji <karim.naaji@gmail.com>

Co-authored-by: Dan Swick <dan.swick@gmail.com>
Co-authored-by: Adriana Babakanian <adriana.babakanian@mapbox.com>
Co-authored-by: Sam Fader <samfader@users.noreply.github.com>
Co-authored-by: Heather Stenson <heather.stenson@mapbox.com>
Co-authored-by: Katy DeCorah <decorah@mapbox.com>
Co-authored-by: jbranigan <john.branigan@mapbox.com>
Co-authored-by: Jeremy Stratman <jstratman@users.noreply.github.com>
Co-authored-by: Mal Wood-Santoro <mal.wood@mapbox.com>
Co-authored-by: Asheem Mamoowala <asheem.mamoowala@mapbox.com>
Co-authored-by: Colleen McGinnis <colleen.mcginnis@mapbox.com>
Co-authored-by: geografa <geografa@users.noreply.github.com>
Co-authored-by: Patrick Leonard <pjleonard37@users.noreply.github.com>
Co-authored-by: David Wicks <david.wicks@mapbox.com>
Co-authored-by: Deven Diliberto <deven.diliberto@mapbox.com>
Co-authored-by: Colleen <colleen.j.mcginnis@gmail.com>
  • Loading branch information
@karimnaaji @danswick
@adrianababakanian @samfader @HeyStenson @jbranigan @jstratman @malwoodsantoro @geografa @pjleonard37 @dpdiliberto @colleenmcginnis
16 people committed Apr 24, 2020
1 parent a60e952 commit ffd5b5d
Show file tree
Hide file tree
Showing 13 changed files with 1,160 additions and 120 deletions.
7 changes: 5 additions & 2 deletions src/geo/lng_lat.js
View file
Expand Up @@ -12,8 +12,10 @@ export const earthRadius = 6371008.8;

/**
* A `LngLat` object represents a given longitude and latitude coordinate, measured in degrees.
* These coordinates are based on the [WGS84 (EPSG:4326) standard](https://en.wikipedia.org/wiki/World_Geodetic_System#WGS84).
*
* Mapbox GL uses longitude, latitude coordinate order (as opposed to latitude, longitude) to match GeoJSON.
* Mapbox GL uses longitude, latitude coordinate order (as opposed to latitude, longitude) to match the
* [GeoJSON specification](https://tools.ietf.org/html/rfc7946).
*
* Note that any Mapbox GL method that accepts a `LngLat` object as an argument or option
* can also accept an `Array` of two numbers and will perform an implicit conversion.
Expand All @@ -22,7 +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(-73.9749, 40.7736);
* var ll = new mapboxgl.LngLat(-123.9749, 40.7736);
* 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/)
Expand Down
9 changes: 9 additions & 0 deletions src/geo/lng_lat_bounds.js
View file
Expand Up @@ -216,6 +216,15 @@ class LngLatBounds {
*
* @param {LngLatLike} lnglat geographic point to check against.
* @returns {boolean} True if the point is within the bounding box.
* @example
* var llb = new mapboxgl.LngLatBounds(
* new mapboxgl.LngLat(-73.9876, 40.7661),
* new mapboxgl.LngLat(-73.9397, 40.8002)
* );
*
* var ll = new mapboxgl.LngLat(-73.9567, 40.7789);
*
* console.log(llb.contains(ll)); // = true
*/
contains(lnglat: LngLatLike) {
const {lng, lat} = LngLat.convert(lnglat);
Expand Down
2 changes: 2 additions & 0 deletions src/index.js
View file
Expand Up @@ -163,6 +163,8 @@ const exported = {
*
* @function clearStorage
* @param {Function} callback Called with an error argument if there is an error.
* @example
* mapboxgl.clearStorage();
*/
clearStorage(callback?: (err: ?Error) => void) {
clearTileCache(callback);
Expand Down
16 changes: 16 additions & 0 deletions src/source/geojson_source.js
View file
Expand Up @@ -230,6 +230,22 @@ class GeoJSONSource extends Evented implements Source {
* @param offset The number of features to skip (e.g. for pagination).
* @param callback A callback to be called when the features are retrieved (`(error, features) => { ... }`).
* @returns {GeoJSONSource} this
* @example
* // Retrieve cluster leaves on click
* map.on('click', 'clusters', function(e) {
* var features = map.queryRenderedFeatures(e.point, {
* layers: ['clusters']
* });
*
* var clusterId = features[0].properties.cluster_id;
* var pointCount = features[0].properties.point_count;
* var clusterSource = map.getSource('clusters');
*
* clusterSource.getClusterLeaves(clusterId, pointCount, 0, function(error, features) {
* // Print cluster leaves in the console
* console.log('Cluster leaves:', error, features);
* })
* });
*/
getClusterLeaves(clusterId: number, limit: number, offset: number, callback: Callback<Array<GeoJSONFeature>>) {
this.actor.send('geojson.getClusterLeaves', {
Expand Down
87 changes: 79 additions & 8 deletions src/ui/camera.js
View file
Expand Up @@ -33,11 +33,28 @@ import type {PaddingOptions} from '../geo/edge_insets';
* @typedef {Object} CameraOptions
* @property {LngLatLike} center The desired center.
* @property {number} zoom The desired zoom level.
* @property {number} bearing The desired bearing, in degrees. The bearing is the compass direction that
* is "up"; for example, a bearing of 90° orients the map so that east is up.
* @property {number} pitch The desired pitch, in degrees.
* @property {number} bearing The desired bearing in degrees. The bearing is the compass direction that
* is "up". For example, `bearing: 90` orients the map so that east is up.
* @property {number} pitch The desired pitch in degrees. The pitch is the angle towards the horizon
* measured in degrees with a range between 0 and 60 degrees. For example, pitch: 0 provides the appearance
* of looking straight down at the map, while pitch: 60 tilts the user's perspective towards the horizon.
* Increasing the pitch value is often used to display 3D objects.
* @property {LngLatLike} around If `zoom` is specified, `around` determines the point around which the zoom is centered.
* @property {PaddingOptions} padding Dimensions in pixels applied on eachs side of the viewport for shifting the vanishing point.
* @property {PaddingOptions} padding Dimensions in pixels applied on each side of the viewport for shifting the vanishing point.
* @example
* // set the map's initial perspective with CameraOptions
* var map = new mapboxgl.Map({
* container: 'map',
* style: 'mapbox://styles/mapbox/streets-v11',
* center: [-73.5804, 45.53483],
* pitch: 60,
* bearing: -60,
* zoom: 10
* });
* @see [Set pitch and bearing](https://docs.mapbox.com/mapbox-gl-js/example/set-perspective/)
* @see [Jump to a series of locations](https://docs.mapbox.com/mapbox-gl-js/example/jump-to/)
* @see [Fly to a location](https://docs.mapbox.com/mapbox-gl-js/example/flyto/)
* @see [Display buildings in 3D](https://docs.mapbox.com/mapbox-gl-js/example/3d-buildings/)
*/
export type CameraOptions = {
center?: LngLatLike,
Expand Down Expand Up @@ -71,14 +88,28 @@ export type AnimationOptions = {
};

/**
* Options for setting padding on a call to {@link Map#fitBounds}. All properties of this object must be
* Options for setting padding on calls to methods such as {@link Map#fitBounds}, {@link Map#fitScreenCoordinates}, and {@link Map#setPadding}. Adjust these options to set the amount of padding in pixels added to the edges of the canvas. Set a uniform padding on all edges or individual values for each edge. All properties of this object must be
* non-negative integers.
*
* @typedef {Object} PaddingOptions
* @property {number} top Padding in pixels from the top of the map canvas.
* @property {number} bottom Padding in pixels from the bottom of the map canvas.
* @property {number} left Padding in pixels from the left of the map canvas.
* @property {number} right Padding in pixels from the right of the map canvas.
*
* @example
* var bbox = [[-79, 43], [-73, 45]];
* map.fitBounds(bbox, {
* padding: {top: 10, bottom:25, left: 15, right: 5}
* });
*
* @example
* var bbox = [[-79, 43], [-73, 45]];
* map.fitBounds(bbox, {
* padding: 20
* });
* @see [Fit to the bounds of a LineString](https://docs.mapbox.com/mapbox-gl-js/example/zoomto-linestring/)
* @see [Fit a map to a bounding box](https://docs.mapbox.com/mapbox-gl-js/example/fitbounds/)
*/

class Camera extends Evented {
Expand Down Expand Up @@ -119,6 +150,12 @@ class Camera extends Evented {
*
* @memberof Map#
* @returns The map's geographical centerpoint.
* @example
* // return a LngLat object such as {lng: 0, lat: 0}
* var center = map.getCenter();
* // access longitude and latitude values directly
* var {longitude, latitude} = map.getCenter();
* @see Tutorial: [Use Mapbox GL JS in a React app](https://docs.mapbox.com/help/tutorials/use-mapbox-gl-js-with-react/#store-the-new-coordinates)
*/
getCenter(): LngLat { return new LngLat(this.transform.center.lng, this.transform.center.lat); }

Expand Down Expand Up @@ -156,15 +193,21 @@ class Camera extends Evented {
}

/**
* Pans the map to the specified location, with an animated transition.
* Pans the map to the specified location with an animated transition.
*
* @memberof Map#
* @param lnglat The location to pan the map to.
* @param options Options object
* @param options Options describing the destination and animation of the transition.
* @param eventData Additional properties to be added to event objects of events triggered by this method.
* @fires movestart
* @fires moveend
* @returns {Map} `this`
* @example
* map.panTo([-74, 38]);
* @example
* // Specify that the panTo animation should last 5000 milliseconds.
* map.panTo([-74, 38], {duration: 5000});
* @see [Update a feature in realtime](https://docs.mapbox.com/mapbox-gl-js/example/live-update-feature/)
*/
panTo(lnglat: LngLatLike, options?: AnimationOptions, eventData?: Object) {
return this.easeTo(extend({
Expand All @@ -177,6 +220,8 @@ class Camera extends Evented {
*
* @memberof Map#
* @returns The map's current zoom level.
* @example
* map.getZoom();
*/
getZoom(): number { return this.transform.zoom; }

Expand All @@ -194,7 +239,7 @@ class Camera extends Evented {
* @fires zoomend
* @returns {Map} `this`
* @example
* // zoom the map to 5
* // Zoom to the zoom level 5 without an animated transition
* map.setZoom(5);
*/
setZoom(zoom: number, eventData?: Object) {
Expand All @@ -216,6 +261,14 @@ class Camera extends Evented {
* @fires moveend
* @fires zoomend
* @returns {Map} `this`
* @example
* // Zoom to the zoom level 5 without an animated transition
* map.zoomTo(5);
* // Zoom to the zoom level 8 with an animated transition
* map.zoomTo(8, {
* duration: 2000,
* offset: [100, 50]
* });
*/
zoomTo(zoom: number, options: ? AnimationOptions, eventData?: Object) {
return this.easeTo(extend({
Expand All @@ -236,6 +289,9 @@ class Camera extends Evented {
* @fires moveend
* @fires zoomend
* @returns {Map} `this`
* @example
* // zoom the map in one level with a custom animation duration
* map.zoomIn({duration: 1000});
*/
zoomIn(options?: AnimationOptions, eventData?: Object) {
this.zoomTo(this.getZoom() + 1, options, eventData);
Expand All @@ -255,6 +311,9 @@ class Camera extends Evented {
* @fires moveend
* @fires zoomend
* @returns {Map} `this`
* @example
* // zoom the map out one level with a custom animation offset
* map.zoomOut({offset: [80, 60]});
*/
zoomOut(options?: AnimationOptions, eventData?: Object) {
this.zoomTo(this.getZoom() - 1, options, eventData);
Expand Down Expand Up @@ -631,6 +690,18 @@ class Camera extends Evented {
* @fires zoomend
* @fires pitchend
* @returns {Map} `this`
* @example
* // jump to coordinates at current zoom
* map.jumpTo({center: [0, 0]});
* // jump with zoom, pitch, and bearing options
* map.jumpTo({
* center: [0, 0],
* zoom: 8,
* pitch: 45,
* bearing: 90
* });
* @see [Jump to a series of locations](https://docs.mapbox.com/mapbox-gl-js/example/jump-to/)
* @see [Update a feature in realtime](https://docs.mapbox.com/mapbox-gl-js/example/live-update-feature/)
*/
jumpTo(options: CameraOptions, eventData?: Object) {
this.stop();
Expand Down
96 changes: 92 additions & 4 deletions src/ui/control/geolocate_control.js
View file
Expand Up @@ -406,10 +406,23 @@ class GeolocateControl extends Evented {
}

/**
* Trigger a geolocation
*
* @returns {boolean} Returns `false` if called before control was added to a map, otherwise returns `true`.
*/
* Programmatically request and move the map to the user's location.
*
* @returns {boolean} Returns `false` if called before control was added to a map, otherwise returns `true`.
* @example
* // Initialize the geolocate control.
* var geolocate = new mapboxgl.GeolocateControl({
* positionOptions: {
* enableHighAccuracy: true
* },
* trackUserLocation: true
* });
* // Add the control to the map.
* map.addControl(geolocate);
* map.on('load', function() {
* geolocate.trigger();
* });
*/
trigger() {
if (!this._setup) {
warnOnce('Geolocate control triggered before added to a map');
Expand Down Expand Up @@ -552,6 +565,21 @@ export default GeolocateControl;
* @memberof GeolocateControl
* @instance
* @property {Position} data The returned [Position](https://developer.mozilla.org/en-US/docs/Web/API/Position) object from the callback in [Geolocation.getCurrentPosition()](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation/getCurrentPosition) or [Geolocation.watchPosition()](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation/watchPosition).
* @example
* // Initialize the geolocate control.
* var geolocate = new mapboxgl.GeolocateControl({
* positionOptions: {
* enableHighAccuracy: true
* },
* trackUserLocation: true
* });
* // Add the control to the map.
* map.addControl(geolocate);
* // Set an event listener that fires
* // when a geolocate event occurs.
* geolocate.on('geolocate', function() {
* console.log('A geolocate event has occurred.')
* });
*
*/

Expand All @@ -562,6 +590,21 @@ export default GeolocateControl;
* @memberof GeolocateControl
* @instance
* @property {PositionError} data The returned [PositionError](https://developer.mozilla.org/en-US/docs/Web/API/PositionError) object from the callback in [Geolocation.getCurrentPosition()](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation/getCurrentPosition) or [Geolocation.watchPosition()](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation/watchPosition).
* @example
* // Initialize the geolocate control.
* var geolocate = new mapboxgl.GeolocateControl({
* positionOptions: {
* enableHighAccuracy: true
* },
* trackUserLocation: true
* });
* // Add the control to the map.
* map.addControl(geolocate);
* // Set an event listener that fires
* // when an error event occurs.
* geolocate.on('error', function() {
* console.log('An error event has occurred.')
* });
*
*/

Expand All @@ -572,6 +615,21 @@ export default GeolocateControl;
* @memberof GeolocateControl
* @instance
* @property {Position} data The returned [Position](https://developer.mozilla.org/en-US/docs/Web/API/Position) object from the callback in [Geolocation.getCurrentPosition()](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation/getCurrentPosition) or [Geolocation.watchPosition()](https://developer.mozilla.org/en-US/docs/Web/API/Geolocation/watchPosition).
* @example
* // Initialize the geolocate control.
* var geolocate = new mapboxgl.GeolocateControl({
* positionOptions: {
* enableHighAccuracy: true
* },
* trackUserLocation: true
* });
* // Add the control to the map.
* map.addControl(geolocate);
* // Set an event listener that fires
* // when an outofmaxbounds event occurs.
* geolocate.on('outofmaxbounds', function() {
* console.log('An outofmaxbounds event has occurred.')
* });
*
*/

Expand All @@ -581,6 +639,21 @@ export default GeolocateControl;
* @event trackuserlocationstart
* @memberof GeolocateControl
* @instance
* @example
* // Initialize the geolocate control.
* var geolocate = new mapboxgl.GeolocateControl({
* positionOptions: {
* enableHighAccuracy: true
* },
* trackUserLocation: true
* });
* // Add the control to the map.
* map.addControl(geolocate);
* // Set an event listener that fires
* // when a trackuserlocationstart event occurs.
* geolocate.on('trackuserlocationstart', function() {
* console.log('A trackuserlocationstart event has occurred.')
* });
*
*/

Expand All @@ -590,5 +663,20 @@ export default GeolocateControl;
* @event trackuserlocationend
* @memberof GeolocateControl
* @instance
* @example
* // Initialize the geolocate control.
* var geolocate = new mapboxgl.GeolocateControl({
* positionOptions: {
* enableHighAccuracy: true
* },
* trackUserLocation: true
* });
* // Add the control to the map.
* map.addControl(geolocate);
* // Set an event listener that fires
* // when a trackuserlocationend event occurs.
* geolocate.on('trackuserlocationend', function() {
* console.log('A trackuserlocationend event has occurred.')
* });
*
*/

0 comments on commit ffd5b5d

Please sign in to comment.