Fix docs (#3611)

* Fix docs

* Fix image generation script

* Fix escape character issues

* Add missing docs annotation

* Update src/ui/handler/tap_drag_zoom.ts

---------

Co-authored-by: neodescis <nsteinbaugh@gmail.com>

build/generate-doc-images.ts

@@ -2,7 +2,6 @@ import path from 'path';
 import fs from 'fs';
 import puppeteer from 'puppeteer';
 import packageJson from '../package.json' assert { type: 'json' };
-import {sleep} from '../src/util/test/util';
 
 const exampleName = process.argv[2];
 const examplePath = path.resolve('test', 'examples');
@@ -24,19 +23,17 @@ async function createImage(exampleName) {
     await page.setContent(html.replaceAll('../../dist', `https://unpkg.com/maplibre-gl@${packageJson.version}/dist`));
 
     // Wait for map to load, then wait two more seconds for images, etc. to load.
-    await page
-        .waitForFunction('map.loaded()')
-        .then(async () => {
-            // Wait for 5 seconds on 3d model examples, since this takes longer to load.
-            const waitTime = exampleName.includes('3d-model') ? 5000 : 1500;
-            console.log(`waiting for ${waitTime} ms`);
-            await sleep(waitTime);
-        })
+    try {
+        await page.waitForFunction('map.loaded()');
+        // Wait for 5 seconds on 3d model examples, since this takes longer to load.
+        const waitTime = exampleName.includes('3d-model') ? 5000 : 1500;
+        console.log(`waiting for ${waitTime} ms`);
+        await new Promise(resolve => setTimeout(resolve, waitTime));
+    } catch (err) {
         // map.loaded() does not evaluate to true within 3 seconds, it's probably an animated example.
         // In this case we take the screenshot immediately.
-        .catch(() => {
-            console.log(`Timed out waiting for map load on ${exampleName}.`);
-        });
+        console.log(`Timed out waiting for map load on ${exampleName}.`);
+    }
 
     await page
         .screenshot({

build/generate-docs.ts

@@ -55,15 +55,15 @@ if (!fs.existsSync(typedocConfig.out)) {
 }
 
 fs.rmSync(path.join(typedocConfig.out, 'README.md'));
-fs.rmSync(path.join(typedocConfig.out, 'modules.md'));
 // Intro file for the API
-const modulesFolder = path.join(typedocConfig.out, 'modules');
-const content = fs.readFileSync(path.join(modulesFolder, `${typedocConfig.internalModule}.md`), 'utf-8');
+const modulesFile = path.join(typedocConfig.out, 'modules.md');
+const content = fs.readFileSync(modulesFile, 'utf-8');
 let lines = content.split('\n');
 const classesLineIndex = lines.indexOf(lines.find(l => l.endsWith('Classes')) as string);
 lines = lines.splice(2, classesLineIndex - 2);
 const contentString = generateAPIIntroMarkdown(lines);
 fs.writeFileSync(path.join(typedocConfig.out, 'README.md'), contentString);
+fs.rmSync(modulesFile);
 
 // Examples manupilation
 const examplesDocsFolder = path.join('docs', 'examples');

docs/index.md

@@ -25,7 +25,7 @@ MapLibre GL JS is a TypeScript library that uses WebGL to render interactive map
 This documentation is divided into several sections:
 
 * [**Main**](./API/README.md) - The Main section holds the following classes
-    * [`Map`](./API/classes/maplibregl.Map.md) object is the map on your page. It lets you access methods and properties for interacting with the map's style and layers, respond to events, and manipulate the user's perspective with the camera.
+    * [`Map`](./API/classes/Map.md) object is the map on your page. It lets you access methods and properties for interacting with the map's style and layers, respond to events, and manipulate the user's perspective with the camera.
     * [`MaplibreGL`](./API/classes/default.md) object is MapLibre GL JS's global properties and options that you might want to access while initializing your map or accessing information about its status.
 * [**Markers and Controls**](./API/README.md#markers-and-controls) - This section describes the user interface elements that you can add to your map. The items in this section exist outside of the map's `canvas` element. This consists of `Marker`, `Popup` and all the controls.
 * [**Geography and geometry**](./API/README.md#geography-and-geometry) - This section includes general utilities and types that relate to working with and manipulating geographic information or geometries.

mkdocs.yml

@@ -36,6 +36,9 @@ markdown_extensions:
   - pymdownx.inlinehilite
   - pymdownx.snippets
   - pymdownx.superfences
+  - pymdownx.escapeall:
+      hardbreak: True
+      nbsp: True
 
 extra:
   social:

src/geo/transform.ts

@@ -460,7 +460,7 @@ export class Transform {
 
     /**
      * Convert from LngLat to world coordinates (Mercator coordinates scaled by 512)
-     * @param lngLat - the lngLat
+     * @param lnglat - the lngLat
      * @returns Point
      */
     project(lnglat: LngLat) {

src/source/geojson_source.ts

@@ -14,13 +14,16 @@ import type {GeoJSONSourceSpecification, PromoteIdSpecification} from '@maplibre
 import type {GeoJSONSourceDiff} from './geojson_source_diff';
 import type {GeoJSONWorkerOptions, LoadGeoJSONParameters} from './geojson_worker_source';
 
+/**
+ * Options object for GeoJSONSource.
+ */
 export type GeoJSONSourceOptions = GeoJSONSourceSpecification & {
     workerOptions?: GeoJSONWorkerOptions;
     collectResourceTiming?: boolean;
     data: GeoJSON.GeoJSON | string;
 }
 
-export type GeoJsonSourceOptions = {
+export type GeoJSONSourceIntenalOptions = {
     data?: GeoJSON.GeoJSON | string | undefined;
     cluster?: boolean;
     clusterMaxZoom?: number;
@@ -113,7 +116,7 @@ export class GeoJSONSource extends Evented implements Source {
     isTileClipped: boolean;
     reparseOverscaled: boolean;
     _data: GeoJSON.GeoJSON | string | undefined;
-    _options: GeoJsonSourceOptions;
+    _options: GeoJSONSourceIntenalOptions;
     workerOptions: GeoJSONWorkerOptions;
     map: Map;
     actor: Actor;

src/ui/control/navigation_control.ts

@@ -100,6 +100,7 @@ export class NavigationControl implements IControl {
         this._compassIcon.style.transform = rotate;
     };
 
+    /** {@inheritDoc IControl.onAdd} */
     onAdd(map: Map) {
         this._map = map;
         if (this.options.showZoom) {
@@ -120,6 +121,7 @@ export class NavigationControl implements IControl {
         return this._container;
     }
 
+    /** {@inheritDoc IControl.onRemove} */
     onRemove() {
         DOM.remove(this._container);
         if (this.options.showZoom) {

src/ui/handler/mouse.ts

@@ -4,8 +4,17 @@ import {DOM} from '../../util/dom';
 import {DragMoveHandler, DragPanResult, DragRotateResult, DragPitchResult, DragHandler} from './drag_handler';
 import {MouseMoveStateManager} from './drag_move_state_manager';
 
+/**
+ * `MousePanHandler` allows the user to pan the map by clicking and dragging
+ */
 export interface MousePanHandler extends DragMoveHandler<DragPanResult, MouseEvent> {}
+/**
+ * `MouseRotateHandler` allows the user to rotate the map by clicking and dragging
+ */
 export interface MouseRotateHandler extends DragMoveHandler<DragRotateResult, MouseEvent> {}
+/**
+ * `MousePitchHandler` allows the user to zoom the map by pitching
+ */
 export interface MousePitchHandler extends DragMoveHandler<DragPitchResult, MouseEvent> {}
 
 const LEFT_BUTTON = 0;

src/ui/handler/shim/drag_rotate.ts

@@ -1,5 +1,8 @@
 import type {MousePitchHandler, MouseRotateHandler} from '../mouse';
 
+/**
+ * Options object for `DragRotateHandler`.
+ */
 export type DragRotateHandlerOptions = {
     /**
      * Control the map pitch in addition to the bearing

src/ui/handler/tap_drag_zoom.ts

@@ -2,6 +2,9 @@ import {Handler} from '../handler_manager';
 import {TapRecognizer, MAX_TAP_INTERVAL, MAX_DIST} from './tap_recognizer';
 import type Point from '@mapbox/point-geometry';
 
+/**
+ * A `TapDragZoomHandler` allows the user to zoom the map at a point by double tapping. It also allows the user pan the map by dragging.
+ */
 export class TapDragZoomHandler implements Handler {
 
     _enabled: boolean;

src/ui/handler/tap_zoom.ts

@@ -4,6 +4,9 @@ import type {Map} from '../map';
 import {TransformProvider} from './transform-provider';
 import {Handler} from '../handler_manager';
 
+/**
+ * A `TapZoomHandler` allows the user to zoom the map at a point by double tapping
+ */
 export class TapZoomHandler implements Handler {
     _tr: TransformProvider;
     _enabled: boolean;

src/ui/handler/touch_pan.ts

@@ -3,6 +3,9 @@ import {indexTouches} from './handler_util';
 import {Handler} from '../handler_manager';
 import type {Map} from '../map';
 
+/**
+ * A `TouchPanHandler` allows the user to pan the map using touch gestures.
+ */
 export class TouchPanHandler implements Handler {
 
     _enabled: boolean;

typedoc.json

@@ -11,11 +11,9 @@
     ],
     "out": "./docs/API",
     "excludeExternals": true,
-    "excludeInternal": true,
+    "placeInternalsInOwningModule": true,
     "excludeNotDocumented": true,
     "treatWarningsAsErrors": true,
-    "intentionallyNotExported": ["CollisionBoxArray"],
-    "internalModule": "maplibregl",
     "entryPoints": ["./src/index.ts"],
     "navigation": {
         "includeCategories": false,