Remove maplibregl prefix from docs (#3628)

* Remove internal mudule from docs * Remove maplibregl prefix from docs * Improve build robustness, Update API intro. * Update build/generate-docs.ts Co-authored-by: Bart Louwers <bart.louwers@gmail.com> --------- Co-authored-by: Bart Louwers <bart.louwers@gmail.com>
maplibre · Jan 28, 2024 · 3c6484d · 3c6484d
1 parent 6f64913
commit 3c6484d
Show file tree

Hide file tree

Showing 24 changed files with 113 additions and 104 deletions.
diff --git a/build/generate-docs.ts b/build/generate-docs.ts
@@ -17,6 +17,15 @@ We recommend looking at the [examples](../examples/index.md) as they will help y
 
 Most of the classes wirtten here have an "Options" object for initialization, it is recommended to check which options exist. 
 
+It is recommended to import what you need and the use it. Some examples for classes assume you did that.
+For example, import the \`Map\` class like this:
+\`\`\`ts
+import {Map} from 'maplibre-gl';
+const map = new Map(...)
+\`\`\`
+
+Import declarations are omitted from the examples for brevity.
+
 `;
     intro += lines.map(l => l.replace('../', './')).join('\n');
     return intro;

diff --git a/package.json b/package.json
@@ -148,7 +148,7 @@
     "generate-typings": "dts-bundle-generator --export-referenced-types --umd-module-name=maplibregl -o ./dist/maplibre-gl.d.ts ./src/index.ts",
     "generate-docs": "typedoc && node --no-warnings --loader ts-node/esm build/generate-docs.ts",
     "generate-images": "node --no-warnings --loader ts-node/esm build/generate-doc-images.ts",
-    "build-dist": "run-p --print-label build-css generate-typings && run-p --print-label build-dev build-csp-dev && run-p --print-label build-prod build-csp",
+    "build-dist": "npm run build-css && npm run generate-typings && npm run build-dev && npm run build-csp-dev && npm run build-prod && npm run build-csp",
     "build-dev": "rollup --configPlugin @rollup/plugin-typescript -c --environment BUILD:dev",
     "watch-dev": "rollup --configPlugin @rollup/plugin-typescript -c --environment BUILD:dev --watch",
     "build-prod": "rollup --configPlugin @rollup/plugin-typescript -c --environment BUILD:production",

diff --git a/src/geo/lng_lat.ts b/src/geo/lng_lat.ts
@@ -15,7 +15,7 @@ export const earthRadius = 6371008.8;
  *
  * @example
  * ```ts
- * let v1 = new maplibregl.LngLat(-122.420679, 37.772537);
+ * let v1 = new LngLat(-122.420679, 37.772537);
  * let v2 = [-122.420679, 37.772537];
  * let v3 = {lon: -122.420679, lat: 37.772537};
  * ```
@@ -43,7 +43,7 @@ export type LngLatLike = LngLat | {
  *
  * @example
  * ```ts
- * let ll = new maplibregl.LngLat(-123.9749, 40.7736);
+ * let ll = new LngLat(-123.9749, 40.7736);
  * ll.lng; // = -123.9749
  * ```
  * @see [Get coordinates of the mouse pointer](https://maplibre.org/maplibre-gl-js/docs/examples/mouse-position/)
@@ -75,7 +75,7 @@ export class LngLat {
      * @returns The wrapped `LngLat` object.
      * @example
      * ```ts
-     * let ll = new maplibregl.LngLat(286.0251, 40.7736);
+     * let ll = new LngLat(286.0251, 40.7736);
      * let wrapped = ll.wrap();
      * wrapped.lng; // = -73.9749
      * ```
@@ -90,7 +90,7 @@ export class LngLat {
      * @returns The coordinates represented as an array of longitude and latitude.
      * @example
      * ```ts
-     * let ll = new maplibregl.LngLat(-73.9749, 40.7736);
+     * let ll = new LngLat(-73.9749, 40.7736);
      * ll.toArray(); // = [-73.9749, 40.7736]
      * ```
      */
@@ -104,7 +104,7 @@ export class LngLat {
      * @returns The coordinates represented as a string of the format `'LngLat(lng, lat)'`.
      * @example
      * ```ts
-     * let ll = new maplibregl.LngLat(-73.9749, 40.7736);
+     * let ll = new LngLat(-73.9749, 40.7736);
      * ll.toString(); // = "LngLat(-73.9749, 40.7736)"
      * ```
      */
@@ -120,8 +120,8 @@ export class LngLat {
      * @returns Distance in meters between the two coordinates.
      * @example
      * ```ts
-     * let new_york = new maplibregl.LngLat(-74.0060, 40.7128);
-     * let los_angeles = new maplibregl.LngLat(-118.2437, 34.0522);
+     * let new_york = new LngLat(-74.0060, 40.7128);
+     * let los_angeles = new LngLat(-118.2437, 34.0522);
      * new_york.distanceTo(los_angeles); // = 3935751.690893987, "true distance" using a non-spherical approximation is ~3966km
      * ```
      */
@@ -146,7 +146,7 @@ export class LngLat {
      * @example
      * ```ts
      * let arr = [-73.9749, 40.7736];
-     * let ll = maplibregl.LngLat.convert(arr);
+     * let ll = LngLat.convert(arr);
      * ll;   // = LngLat {lng: -73.9749, lat: 40.7736}
      * ```
      */

diff --git a/src/geo/lng_lat_bounds.ts b/src/geo/lng_lat_bounds.ts
@@ -9,11 +9,11 @@ import type {LngLatLike} from './lng_lat';
  *
  * @example
  * ```ts
- * let v1 = new maplibregl.LngLatBounds(
- *   new maplibregl.LngLat(-73.9876, 40.7661),
- *   new maplibregl.LngLat(-73.9397, 40.8002)
+ * let v1 = new LngLatBounds(
+ *   new LngLat(-73.9876, 40.7661),
+ *   new LngLat(-73.9397, 40.8002)
  * );
- * let v2 = new maplibregl.LngLatBounds([-73.9876, 40.7661], [-73.9397, 40.8002])
+ * let v2 = new LngLatBounds([-73.9876, 40.7661], [-73.9397, 40.8002])
  * let v3 = [[-73.9876, 40.7661], [-73.9397, 40.8002]];
  * ```
  */
@@ -33,9 +33,9 @@ export type LngLatBoundsLike = LngLatBounds | [LngLatLike, LngLatLike] | [number
  *
  * @example
  * ```ts
- * let sw = new maplibregl.LngLat(-73.9876, 40.7661);
- * let ne = new maplibregl.LngLat(-73.9397, 40.8002);
- * let llb = new maplibregl.LngLatBounds(sw, ne);
+ * let sw = new LngLat(-73.9876, 40.7661);
+ * let ne = new LngLat(-73.9397, 40.8002);
+ * let llb = new LngLatBounds(sw, ne);
  * ```
  */
 export class LngLatBounds {
@@ -49,17 +49,17 @@ export class LngLatBounds {
      * @param ne - The northeast corner of the bounding box.
      * @example
      * ```ts
-     * let sw = new maplibregl.LngLat(-73.9876, 40.7661);
-     * let ne = new maplibregl.LngLat(-73.9397, 40.8002);
-     * let llb = new maplibregl.LngLatBounds(sw, ne);
+     * let sw = new LngLat(-73.9876, 40.7661);
+     * let ne = new LngLat(-73.9397, 40.8002);
+     * let llb = new LngLatBounds(sw, ne);
      * ```
      * OR
      * ```ts
-     * let llb = new maplibregl.LngLatBounds([-73.9876, 40.7661, -73.9397, 40.8002]);
+     * let llb = new LngLatBounds([-73.9876, 40.7661, -73.9397, 40.8002]);
      * ```
      * OR
      * ```ts
-     * let llb = new maplibregl.LngLatBounds([sw, ne]);
+     * let llb = new LngLatBounds([sw, ne]);
      * ```
      */
     constructor(sw?: LngLatLike | [number, number, number, number] | [LngLatLike, LngLatLike], ne?: LngLatLike) {
@@ -157,7 +157,7 @@ export class LngLatBounds {
      * @returns The bounding box's center.
      * @example
      * ```ts
-     * let llb = new maplibregl.LngLatBounds([-73.9876, 40.7661], [-73.9397, 40.8002]);
+     * let llb = new LngLatBounds([-73.9876, 40.7661], [-73.9397, 40.8002]);
      * llb.getCenter(); // = LngLat {lng: -73.96365, lat: 40.78315}
      * ```
      */
@@ -228,7 +228,7 @@ export class LngLatBounds {
      * southwest and northeast coordinates of the bounding represented as arrays of numbers.
      * @example
      * ```ts
-     * let llb = new maplibregl.LngLatBounds([-73.9876, 40.7661], [-73.9397, 40.8002]);
+     * let llb = new LngLatBounds([-73.9876, 40.7661], [-73.9397, 40.8002]);
      * llb.toArray(); // = [[-73.9876, 40.7661], [-73.9397, 40.8002]]
      * ```
      */
@@ -243,7 +243,7 @@ export class LngLatBounds {
      * `'LngLatBounds(LngLat(lng, lat), LngLat(lng, lat))'`.
      * @example
      * ```ts
-     * let llb = new maplibregl.LngLatBounds([-73.9876, 40.7661], [-73.9397, 40.8002]);
+     * let llb = new LngLatBounds([-73.9876, 40.7661], [-73.9397, 40.8002]);
      * llb.toString(); // = "LngLatBounds(LngLat(-73.9876, 40.7661), LngLat(-73.9397, 40.8002))"
      * ```
      */
@@ -267,12 +267,12 @@ export class LngLatBounds {
      * @returns `true` if the point is within the bounding box.
      * @example
      * ```ts
-     * let llb = new maplibregl.LngLatBounds(
-     *   new maplibregl.LngLat(-73.9876, 40.7661),
-     *   new maplibregl.LngLat(-73.9397, 40.8002)
+     * let llb = new LngLatBounds(
+     *   new LngLat(-73.9876, 40.7661),
+     *   new LngLat(-73.9397, 40.8002)
      * );
      *
-     * let ll = new maplibregl.LngLat(-73.9567, 40.7789);
+     * let ll = new LngLat(-73.9567, 40.7789);
      *
      * console.log(llb.contains(ll)); // = true
      * ```
@@ -301,7 +301,7 @@ export class LngLatBounds {
      * @example
      * ```ts
      * let arr = [[-73.9876, 40.7661], [-73.9397, 40.8002]];
-     * let llb = maplibregl.LngLatBounds.convert(arr); // = LngLatBounds {_sw: LngLat {lng: -73.9876, lat: 40.7661}, _ne: LngLat {lng: -73.9397, lat: 40.8002}}
+     * let llb = LngLatBounds.convert(arr); // = LngLatBounds {_sw: LngLat {lng: -73.9876, lat: 40.7661}, _ne: LngLat {lng: -73.9397, lat: 40.8002}}
      * ```
      */
     static convert(input: LngLatBoundsLike | null): LngLatBounds {
@@ -318,8 +318,8 @@ export class LngLatBounds {
      * @returns A new `LngLatBounds` object representing the coordinates extended by the `radius`.
      * @example
      * ```ts
-     * let center = new maplibregl.LngLat(-73.9749, 40.7736);
-     * maplibregl.LngLatBounds.fromLngLat(100).toArray(); // = [[-73.97501862141328, 40.77351016847229], [-73.97478137858673, 40.77368983152771]]
+     * let center = new LngLat(-73.9749, 40.7736);
+     * LngLatBounds.fromLngLat(100).toArray(); // = [[-73.97501862141328, 40.77351016847229], [-73.97478137858673, 40.77368983152771]]
      * ```
      */
     static fromLngLat(center: LngLat, radius:number = 0): LngLatBounds {

diff --git a/src/geo/mercator_coordinate.ts b/src/geo/mercator_coordinate.ts
@@ -70,7 +70,7 @@ export function mercatorScale(lat: number) {
  *
  * @example
  * ```ts
- * let nullIsland = new maplibregl.MercatorCoordinate(0.5, 0.5, 0);
+ * let nullIsland = new MercatorCoordinate(0.5, 0.5, 0);
  * ```
  * @see [Add a custom style layer](https://maplibre.org/maplibre-gl-js/docs/examples/custom-style-layer/)
  */
@@ -98,7 +98,7 @@ export class MercatorCoordinate implements IMercatorCoordinate {
      * @returns The projected mercator coordinate.
      * @example
      * ```ts
-     * let coord = maplibregl.MercatorCoordinate.fromLngLat({ lng: 0, lat: 0}, 0);
+     * let coord = MercatorCoordinate.fromLngLat({ lng: 0, lat: 0}, 0);
      * coord; // MercatorCoordinate(0.5, 0.5, 0)
      * ```
      */
@@ -117,7 +117,7 @@ export class MercatorCoordinate implements IMercatorCoordinate {
      * @returns The `LngLat` object.
      * @example
      * ```ts
-     * let coord = new maplibregl.MercatorCoordinate(0.5, 0.5, 0);
+     * let coord = new MercatorCoordinate(0.5, 0.5, 0);
      * let lngLat = coord.toLngLat(); // LngLat(0, 0)
      * ```
      */
@@ -133,7 +133,7 @@ export class MercatorCoordinate implements IMercatorCoordinate {
      * @returns The altitude in meters.
      * @example
      * ```ts
-     * let coord = new maplibregl.MercatorCoordinate(0, 0, 0.02);
+     * let coord = new MercatorCoordinate(0, 0, 0.02);
      * coord.toAltitude(); // 6914.281956295339
      * ```
      */

diff --git a/src/index.ts b/src/index.ts
@@ -58,7 +58,7 @@ export type * from '@maplibre/maplibre-gl-style-spec';
  * rtl text will then be rendered only after the plugin finishes loading.
  * @example
  * ```ts
- * maplibregl.setRTLTextPlugin('https://unpkg.com/@mapbox/mapbox-gl-rtl-text@0.2.3/mapbox-gl-rtl-text.js', false);
+ * setRTLTextPlugin('https://unpkg.com/@mapbox/mapbox-gl-rtl-text@0.2.3/mapbox-gl-rtl-text.js', false);
  * ```
  * @see [Add support for right-to-left scripts](https://maplibre.org/maplibre-gl-js/docs/examples/mapbox-gl-rtl-text/)
  */
@@ -70,7 +70,7 @@ function setRTLTextPlugin(pluginURL: string, lazy: boolean) { return rtlMainThre
  *
  * @example
  * ```ts
- * const pluginStatus = maplibregl.getRTLTextPluginStatus();
+ * const pluginStatus = getRTLTextPluginStatus();
  * ```
  */
 function getRTLTextPluginStatus() { return rtlMainThreadPluginFactory().getRTLTextPluginStatus(); }
@@ -87,7 +87,7 @@ function getVersion() { return version; }
  * @returns Number of workers currently configured.
  * @example
  * ```ts
- * const workerCount = maplibregl.getWorkerCount()
+ * const workerCount = getWorkerCount()
  * ```
  */
 function getWorkerCount() { return WorkerPool.workerCount; }
@@ -98,7 +98,7 @@ function getWorkerCount() { return WorkerPool.workerCount; }
  *
  * @example
  * ```ts
- * maplibregl.setWorkerCount(2);
+ * setWorkerCount(2);
  * ```
  */
 function setWorkerCount(count: number) { WorkerPool.workerCount = count; }
@@ -109,7 +109,7 @@ function setWorkerCount(count: number) { WorkerPool.workerCount = count; }
  * @returns Number of parallel requests currently configured.
  * @example
  * ```ts
- * maplibregl.getMaxParallelImageRequests();
+ * getMaxParallelImageRequests();
  * ```
  */
 function getMaxParallelImageRequests() { return config.MAX_PARALLEL_IMAGE_REQUESTS; }
@@ -119,7 +119,7 @@ function getMaxParallelImageRequests() { return config.MAX_PARALLEL_IMAGE_REQUES
  *
  * @example
  * ```ts
- * maplibregl.setMaxParallelImageRequests(10);
+ * setMaxParallelImageRequests(10);
  * ```
  */
 function setMaxParallelImageRequests(numRequests: number) { config.MAX_PARALLEL_IMAGE_REQUESTS = numRequests; }
@@ -160,7 +160,7 @@ function setWorkerUrl(value: string) { config.WORKER_URL = value; }
  * self.addPRotocol('custom', loadFn);
  *
  * // main.js
- * maplibregl.importScriptInWorkers('add-protocol-worker.js');
+ * importScriptInWorkers('add-protocol-worker.js');
  * ```
  */
 function importScriptInWorkers(workerUrl: string) { return getGlobalDispatcher().broadcast('importScript', workerUrl); }

diff --git a/src/source/protocol_crud.ts b/src/source/protocol_crud.ts
@@ -15,7 +15,7 @@ export function getProtocol(url: string) {
  * @example
  * ```ts
  * // This will fetch a file using the fetch API (this is obviously a non interesting example...)
- * maplibregl.addProtocol('custom', async (params, abortController) => {
+ * addProtocol('custom', async (params, abortController) => {
  *      const t = await fetch(`https://${params.url.split("://")[1]}`);
  *      if (t.status == 200) {
  *          const buffer = await t.arrayBuffer();
@@ -25,7 +25,7 @@ export function getProtocol(url: string) {
  *      }
  *  });
  * // the following is an example of a way to return an error when trying to load a tile
- * maplibregl.addProtocol('custom2', async (params, abortController) => {
+ * addProtocol('custom2', async (params, abortController) => {
  *      throw new Error('someErrorMessage'));
  * });
  * ```
@@ -40,7 +40,7 @@ export function addProtocol(customProtocol: string, loadFn: AddProtocolAction) {
  * @param customProtocol - the custom protocol to remove registration for
  * @example
  * ```ts
- * maplibregl.removeProtocol('custom');
+ * removeProtocol('custom');
  * ```
  */
 export function removeProtocol(customProtocol: string) {

diff --git a/src/ui/camera.ts b/src/ui/camera.ts
@@ -39,7 +39,7 @@ export type RequireAtLeastOne<T> = { [K in keyof T]-?: Required<Pick<T, K>> & Pa
  * @example
  * Set the map's initial perspective with CameraOptions
  * ```ts
- * let map = new maplibregl.Map({
+ * let map = new Map({
  *   container: 'map',
  *   style: 'https://demotiles.maplibre.org/style.json',
  *   center: [-73.5804, 45.53483],

diff --git a/src/ui/control/attribution_control.ts b/src/ui/control/attribution_control.ts
@@ -25,8 +25,8 @@ type AttributionControlOptions = {
  * @group Markers and Controls
  * @example
  * ```ts
- * let map = new maplibregl.Map({attributionControl: false})
- *     .addControl(new maplibregl.AttributionControl({
+ * let map = new Map({attributionControl: false})
+ *     .addControl(new AttributionControl({
  *         compact: true
  *     }));
  * ```

diff --git a/src/ui/control/fullscreen_control.ts b/src/ui/control/fullscreen_control.ts
@@ -27,7 +27,7 @@ type FullscreenControlOptions = {
  *
  * @example
  * ```ts
- * map.addControl(new maplibregl.FullscreenControl({container: document.querySelector('body')}));
+ * map.addControl(new FullscreenControl({container: document.querySelector('body')}));
  * ```
  * @see [View a fullscreen map](https://maplibre.org/maplibre-gl-js/docs/examples/fullscreen/)
  *