Docs: Add JSDoc to core files (#1509)

* Add docs for the loaders

* Update utilities docs

* Add TilesRendererBase jsdoc

* Update for constants

* Update inline function support

* Add events

* Add Babylon docs

* cleanup

* Update output

Author: gkjohnson

src/babylonjs/renderer/loaders/B3DMLoader.js

@@ -2,16 +2,38 @@ import { Matrix } from '@babylonjs/core/Maths/math.vector';
 import { B3DMLoaderBase } from '3d-tiles-renderer/core';
 import { GLTFLoader } from './GLTFLoader.js';
 
+/**
+ * @classdesc
+ * Babylon.js loader for B3DM (Batched 3D Model) tile content. Parses the B3DM binary
+ * structure and delegates embedded GLB loading to GLTFLoader.
+ * @augments B3DMLoaderBase
+ */
 export class B3DMLoader extends B3DMLoaderBase {
 
+	/**
+	 * @param {Scene} scene - The Babylon.js scene to load assets into.
+	 */
 	constructor( scene ) {
 
 		super();
+		/**
+		 * The Babylon.js scene assets are loaded into.
+		 * @type {Scene}
+		 */
 		this.scene = scene;
+		/**
+		 * Transform applied after loading to correct coordinate system orientation.
+		 * @type {Matrix}
+		 */
 		this.adjustmentTransform = Matrix.Identity();
 
 	}
 
+	/**
+	 * @param {ArrayBuffer} buffer - The raw B3DM file data.
+	 * @param {string} uri - URI used for resolving relative resources.
+	 * @returns {Promise<Object>}
+	 */
 	async parse( buffer, uri ) {
 
 		const b3dm = super.parse( buffer );

src/babylonjs/renderer/loaders/GLTFLoader.js

@@ -5,17 +5,39 @@ import '@babylonjs/loaders/glTF/2.0';
 
 const _worldMatrix = /* @__PURE__ */ Matrix.Identity();
 
+/**
+ * @classdesc
+ * Babylon.js loader for GLTF and GLB tile content. Loads a buffer into a Babylon.js scene
+ * and applies an optional adjustment transform for coordinate-system correction.
+ * @augments LoaderBase
+ */
 export class GLTFLoader extends LoaderBase {
 
+	/**
+	 * @param {Scene} scene - The Babylon.js scene to load assets into.
+	 */
 	constructor( scene ) {
 
 		super();
+		/**
+		 * The Babylon.js scene assets are loaded into.
+		 * @type {Scene}
+		 */
 		this.scene = scene;
+		/**
+		 * Transform applied after loading to correct coordinate system orientation.
+		 * @type {Matrix}
+		 */
 		this.adjustmentTransform = Matrix.Identity();
 
 	}
 
-
+	/**
+	 * @param {ArrayBuffer} buffer - The raw GLTF or GLB file data.
+	 * @param {string} uri - URI used for resolving relative resources.
+	 * @param {string} extension - File extension, either `'gltf'` or `'glb'`.
+	 * @returns {Promise<{scene: TransformNode, container: AssetContainer, metadata: Object|null}>}
+	 */
 	async parse( buffer, uri, extension ) {
 
 		const { scene, workingPath, adjustmentTransform } = this;

src/babylonjs/renderer/tiles/TilesRenderer.js

@@ -14,14 +14,37 @@ const _cameraPositionInTiles = /* @__PURE__ */ new Vector3();
 const _frustumPlanes = /* @__PURE__ */ new Array( 6 ).fill( null ).map( () => new Plane( 0, 0, 0, 0 ) );
 
 // TODO: implementation does not support left handed coordinate system
+/**
+ * @classdesc
+ * Babylon.js implementation of the 3D Tiles renderer. Manages tile loading, caching, traversal,
+ * and scene management using the Babylon.js scene graph and camera APIs. Dispatches all events
+ * defined by TilesRendererBase via Babylon.js Observables.
+ * @augments TilesRendererBase
+ */
 export class TilesRenderer extends TilesRendererBase {
 
+	/**
+	 * @param {string} url - URL of the root tileset JSON.
+	 * @param {Scene} scene - The Babylon.js scene to render tiles into.
+	 */
 	constructor( url, scene ) {
 
 		super( url );
 
+		/**
+		 * The Babylon.js scene tiles are rendered into.
+		 * @type {Scene}
+		 */
 		this.scene = scene;
+		/**
+		 * Root node that all loaded tile scenes are parented to.
+		 * @type {TransformNode}
+		 */
 		this.group = new TransformNode( 'tiles-root', scene );
+		/**
+		 * Whether to enable collision checking on loaded tile meshes.
+		 * @type {boolean}
+		 */
 		this.checkCollisions = false;
 		this._upRotationMatrix = Matrix.Identity();
 
@@ -336,6 +359,10 @@ export class TilesRenderer extends TilesRendererBase {
 
 	}
 
+	/**
+	 * Disposes the renderer, releasing all loaded tile content and the root transform node.
+	 * @returns {void}
+	 */
 	dispose() {
 
 		super.dispose();

src/core/renderer/constants.js

@@ -1,13 +1,56 @@
-// FAILED is negative so lru cache priority sorting will unload it first
+/**
+ * Tile content failed to load. Sorted first for eviction by the LRU cache.
+ * @type {number}
+ */
 export const FAILED = - 1;
+
+/**
+ * Tile content has not been requested.
+ * @type {number}
+ */
 export const UNLOADED = 0;
+
+/**
+ * Tile content is queued for download.
+ * @type {number}
+ */
 export const QUEUED = 1;
+
+/**
+ * Tile content is currently downloading.
+ * @type {number}
+ */
 export const LOADING = 2;
+
+/**
+ * Tile content has been downloaded and is being parsed.
+ * @type {number}
+ */
 export const PARSING = 3;
+
+/**
+ * Tile content has been parsed and is ready to display.
+ * @type {number}
+ */
 export const LOADED = 4;
 
 // https://en.wikipedia.org/wiki/World_Geodetic_System
 // https://en.wikipedia.org/wiki/Flattening
+
+/**
+ * WGS84 ellipsoid semi-major axis radius in meters.
+ * @type {number}
+ */
 export const WGS84_RADIUS = 6378137;
+
+/**
+ * WGS84 ellipsoid flattening factor.
+ * @type {number}
+ */
 export const WGS84_FLATTENING = 1 / 298.257223563;
+
+/**
+ * WGS84 ellipsoid height offset (difference between equatorial and polar radii) in meters.
+ * @type {number}
+ */
 export const WGS84_HEIGHT = - ( WGS84_FLATTENING * WGS84_RADIUS - WGS84_RADIUS );

src/core/renderer/index.d.ts

@@ -1,7 +1,6 @@
 // common
 export * from './tiles/TilesRendererBase.js';
-export { Tile } from './tiles/Tile.js';
-export { TileBase } from './tiles/TileBase.js';
+export { Tile, TileInternalData, TileTraversalData } from './tiles/Tile.js';
 export { Tileset } from './tiles/Tileset.js';
 export * from './loaders/B3DMLoaderBase.js';
 export * from './loaders/I3DMLoaderBase.js';

src/core/renderer/loaders/B3DMLoaderBase.js

@@ -6,8 +6,20 @@ import { FeatureTable } from '../utilities/FeatureTable.js';
 import { LoaderBase } from './LoaderBase.js';
 import { readMagicBytes } from '../utilities/LoaderUtils.js';
 
+/**
+ * Base loader for the B3DM (Batched 3D Model) tile format. Parses the B3DM binary
+ * structure and extracts the embedded GLB bytes along with batch and feature tables.
+ * Extend this class to integrate B3DM loading into a specific rendering engine.
+ *
+ * @extends LoaderBase
+ */
 export class B3DMLoaderBase extends LoaderBase {
 
+	/**
+	 * Parses a B3DM buffer and returns the raw tile data.
+	 * @param {ArrayBuffer} buffer
+	 * @returns {{ version: string, featureTable: FeatureTable, batchTable: BatchTable, glbBytes: Uint8Array }}
+	 */
 	parse( buffer ) {
 
 		// TODO: this should be able to take a uint8array with an offset and length

src/core/renderer/loaders/CMPTLoaderBase.js

@@ -3,8 +3,20 @@
 import { LoaderBase } from './LoaderBase.js';
 import { readMagicBytes } from '../utilities/LoaderUtils.js';
 
+/**
+ * Base loader for the CMPT (Composite) tile format. Parses the CMPT binary structure
+ * and returns the individual inner tile buffers with their format types. Extend this
+ * class to integrate CMPT loading into a specific rendering engine.
+ *
+ * @extends LoaderBase
+ */
 export class CMPTLoaderBase extends LoaderBase {
 
+	/**
+	 * Parses a CMPT buffer and returns an object containing each inner tile's type and raw buffer.
+	 * @param {ArrayBuffer} buffer
+	 * @returns {{ version: string, tiles: Array<{ type: string, buffer: Uint8Array, version: number }> }}
+	 */
 	parse( buffer ) {
 
 		const dataView = new DataView( buffer );

src/core/renderer/loaders/I3DMLoaderBase.js

@@ -6,8 +6,21 @@ import { FeatureTable } from '../utilities/FeatureTable.js';
 import { LoaderBase } from './LoaderBase.js';
 import { readMagicBytes, arrayToString, getWorkingPath } from '../utilities/LoaderUtils.js';
 
+/**
+ * Base loader for the I3DM (Instanced 3D Model) tile format. Parses the I3DM binary
+ * structure and extracts the embedded GLB bytes (or fetches an external GLTF) along
+ * with batch and feature tables. Extend this class to integrate I3DM loading into a
+ * specific rendering engine.
+ *
+ * @extends LoaderBase
+ */
 export class I3DMLoaderBase extends LoaderBase {
 
+	/**
+	 * Parses an I3DM buffer and returns the raw tile data.
+	 * @param {ArrayBuffer} buffer
+	 * @returns {Promise<{ version: string, featureTable: FeatureTable, batchTable: BatchTable, glbBytes: Uint8Array, gltfWorkingPath: string }>}
+	 */
 	parse( buffer ) {
 
 		const dataView = new DataView( buffer );

src/core/renderer/loaders/LoaderBase.js

@@ -1,21 +1,43 @@
 import { getWorkingPath } from '../utilities/LoaderUtils.js';
 
+/**
+ * Base class for all 3D Tiles content loaders. Handles fetching and parsing tile content.
+ */
 export class LoaderBase {
 
 	constructor() {
 
+		/**
+		 * Options passed to `fetch` when loading tile content.
+		 * @type {Object}
+		 */
 		this.fetchOptions = {};
+
+		/**
+		 * Base URL used to resolve relative external URLs.
+		 * @type {string}
+		 */
 		this.workingPath = '';
 
 	}
 
+	/**
+	 * @deprecated Use `loadAsync` instead.
+	 * @param {string} url
+	 * @returns {Promise<any>}
+	 */
 	load( ...args ) {
 
 		console.warn( 'Loader: "load" function has been deprecated in favor of "loadAsync".' );
 		return this.loadAsync( ...args );
 
 	}
 
+	/**
+	 * Fetches and parses content from the given URL.
+	 * @param {string} url
+	 * @returns {Promise<any>}
+	 */
 	loadAsync( url ) {
 
 		return fetch( url, this.fetchOptions )
@@ -44,12 +66,22 @@ export class LoaderBase {
 
 	}
 
+	/**
+	 * Resolves a relative URL against `workingPath`.
+	 * @param {string} url
+	 * @returns {string}
+	 */
 	resolveExternalURL( url ) {
 
 		return new URL( url, this.workingPath ).href;
 
 	}
 
+	/**
+	 * Parses a raw buffer into a tile result object. Must be implemented by subclasses.
+	 * @param {ArrayBuffer} buffer
+	 * @returns {any}
+	 */
 	parse( buffer ) {
 
 		throw new Error( 'LoaderBase: Parse not implemented.' );

src/core/renderer/loaders/PNTSLoaderBase.js

@@ -6,8 +6,21 @@ import { FeatureTable } from '../utilities/FeatureTable.js';
 import { readMagicBytes } from '../utilities/LoaderUtils.js';
 import { LoaderBase } from './LoaderBase.js';
 
+/**
+ * Base loader for the PNTS (Point Cloud) tile format. Parses the PNTS binary
+ * structure and extracts the feature and batch tables containing point positions,
+ * colors, and normals. Extend this class to integrate PNTS loading into a specific
+ * rendering engine.
+ *
+ * @extends LoaderBase
+ */
 export class PNTSLoaderBase extends LoaderBase {
 
+	/**
+	 * Parses a PNTS buffer and returns the raw tile data.
+	 * @param {ArrayBuffer} buffer
+	 * @returns {Promise<{ version: string, featureTable: FeatureTable, batchTable: BatchTable }>}
+	 */
 	parse( buffer ) {
 
 		const dataView = new DataView( buffer );