Add notes and warnings

Author: gkjohnson

eslint.config.js

@@ -110,6 +110,7 @@ export default [
 		},
 		settings: {
 			jsdoc: {
+				definedTags: [ 'warn', 'note' ],
 				preferredTypes: {
 					Any: 'any',
 					Boolean: 'boolean',

src/core/renderer/tiles/TilesRendererBase.js

@@ -445,24 +445,28 @@ export class TilesRendererBase {
 
 		/**
 		 * LRU cache managing loaded tile lifecycle and memory eviction.
+		 * @note Cannot be replaced once `update()` has been called for the first time.
 		 * @type {LRUCache}
 		 */
 		this.lruCache = lruCache;
 
 		/**
-		 * Priority queue controlling concurrent tile downloads.
+		 * Priority queue controlling concurrent tile downloads. Max jobs defaults to `25`.
+		 * @note Cannot be replaced once `update()` has been called for the first time.
 		 * @type {PriorityQueue}
 		 */
 		this.downloadQueue = downloadQueue;
 
 		/**
-		 * Priority queue controlling concurrent tile parsing.
+		 * Priority queue controlling concurrent tile parsing. Max jobs defaults to `5`.
+		 * @note Cannot be modified once `update()` has been called for the first time.
 		 * @type {PriorityQueue}
 		 */
 		this.parseQueue = parseQueue;
 
 		/**
-		 * Priority queue controlling deferred tile child preprocessing.
+		 * Priority queue for expanding and initializing tiles for traversal. Max jobs defaults to `25`.
+		 * @note Cannot be replaced once `update()` has been called for the first time.
 		 * @type {PriorityQueue}
 		 */
 		this.processNodeQueue = processNodeQueue;
@@ -510,15 +514,21 @@ export class TilesRendererBase {
 		// options
 
 		/**
-		 * Target screen-space error in pixels. Tiles with a higher SSE are subdivided.
+		 * Target screen-space error in pixels to aim for when updating the geometry. Tiles will
+		 * not render if they are below this level of screen-space error. See the
+		 * [geometric error section](https://github.com/CesiumGS/3d-tiles/tree/master/specification#geometric-error)
+		 * of the 3D Tiles specification for more information.
 		 * @type {number}
 		 */
 		this.errorTarget = 16.0;
 		this._errorThreshold = Infinity;
 
 		/**
-		 * If true, tiles are displayed at their current LOD while waiting for higher-detail
-		 * children to finish loading, rather than hiding them.
+		 * "Active tiles" are those that are loaded and available but not necessarily visible.
+		 * These tiles are useful for raycasting off-camera or for casting shadows. Active tiles
+		 * not currently in a camera frustum are removed from the scene as an optimization.
+		 * Setting this to `true` keeps them in the scene so they can be rendered from an outside
+		 * camera view not accounted for by the tiles renderer.
 		 * @type {boolean}
 		 */
 		this.displayActiveTiles = false;
@@ -530,20 +540,38 @@ export class TilesRendererBase {
 		this.maxDepth = Infinity;
 
 		/**
-		 * If true, uses an optimized traversal strategy that prioritizes distance over error.
+		 * **Experimental.** Enables an optimized tile loading strategy that loads only the tiles
+		 * needed for the current view, reducing memory usage and improving initial load times.
+		 * Tiles are loaded independently based on screen-space error without requiring all parent
+		 * tiles to load first. Prevents visual gaps and flashing during camera movement.
+		 *
+		 * Based in part on [Cesium Native tile selection](https://cesium.com/learn/cesium-native/ref-doc/selection-algorithm-details.html).
+		 *
+		 * Default is `false`, which uses the previous approach of loading all parent and sibling
+		 * tiles for guaranteed smooth transitions.
+		 * @warn Setting is currently incompatible with plugins that split tiles and on-the-fly generate and
+		 * dispose of child tiles including the `ImageOverlayPlugin` `enableTileSplitting` setting,
+		 * `QuantizedMeshPlugin`, & `ImageFormatPlugin` subclasses (XYZ, TMS, etc). Any tile sets
+		 * that share caches or queues must also use the same setting.
 		 * @type {boolean}
 		 */
 		this.optimizedLoadStrategy = false;
 
 		/**
-		 * If true, sibling tiles of visible tiles are also loaded to reduce pop-in during camera movement.
+		 * **Experimental.** When `true`, sibling tiles are loaded together to prevent gaps during
+		 * camera movement. When `false`, only visible tiles are loaded, minimizing memory but
+		 * potentially causing brief gaps during rapid movement.
+		 *
+		 * Only applies when `optimizedLoadStrategy` is enabled.
 		 * @type {boolean}
 		 */
 		this.loadSiblings = true;
 
 		/**
-		 * Maximum number of tile children to preprocess per `update` call. Excess tiles are deferred
-		 * to `processNodeQueue`.
+		 * The number of tiles to process immediately when traversing the tile set to determine
+		 * what to render. Lower numbers prevent frame hiccups caused by processing too many tiles
+		 * at once when a new tile set is available, while higher values process more tiles
+		 * immediately so data can be downloaded and displayed sooner.
 		 * @type {number}
 		 */
 		this.maxTilesProcessed = 250;

src/core/renderer/utilities/BatchTable.js

@@ -67,7 +67,9 @@ export class BatchTable extends FeatureTable {
 	}
 
 	/**
-	 * Returns all batch table properties for the given feature id as an object.
+	 * Returns an object with all properties of the batch table and its extensions for the
+	 * given feature id. A `target` object can be specified to store the result. Throws if
+	 * `id` is out of bounds.
 	 * @param {number} id - Feature index (0 to count - 1)
 	 * @param {Object} [target={}] - Optional object to write properties into
 	 * @returns {Object}
@@ -104,9 +106,10 @@ export class BatchTable extends FeatureTable {
 	}
 
 	/**
-	 * Returns the full typed array of values for the given property key across all features.
+	 * Returns the array of values for the given property key across all features. Returns
+	 * `null` if the key is not in the table.
 	 * @param {string} key
-	 * @returns {number | string | ArrayBufferView}
+	 * @returns {Array | TypedArray | null}
 	 */
 	getPropertyArray( key ) {
 

src/core/renderer/utilities/LRUCache.js

@@ -69,12 +69,14 @@ class LRUCache {
 
 		/**
 		 * Minimum total bytes to retain after eviction.
+		 * @note Only works with three.js r166 or higher.
 		 * @type {number}
 		 */
 		this.minBytesSize = 0.3 * GIGABYTE_BYTES;
 
 		/**
 		 * Maximum total bytes before eviction is triggered.
+		 * @note Only works with three.js r166 or higher.
 		 * @type {number}
 		 */
 		this.maxBytesSize = 0.4 * GIGABYTE_BYTES;

src/core/renderer/utilities/PriorityQueue.js

@@ -79,7 +79,10 @@ export class PriorityQueue {
 		this.priorityCallback = null;
 
 		/**
-		 * Callback used to schedule a deferred job run. Defaults to `requestAnimationFrame`.
+		 * Callback used to schedule when to run jobs next, so more work doesn't happen in a
+		 * single frame than there is time for. Defaults to `requestAnimationFrame`. Should be
+		 * overridden in scenarios where `requestAnimationFrame` is not reliable, such as when
+		 * running in WebXR.
 		 * @type {SchedulingCallback}
 		 */
 		this.schedulingCallback = func => {

src/three/plugins/batched/BatchedTilesPlugin.js

@@ -13,10 +13,10 @@ _whiteTex.needsUpdate = true;
  * and optimized as new geometry is added and removed. Note that the `renderer` field is
  * required. Requires Three.js r170 or later.
  *
- * **Warning:** All tile geometry rendered with `BatchedMesh` will use the same material and
- * only a single material map is supported. Only tile geometry containing a single mesh is
- * supported. Not compatible with plugins that modify mesh materials or rely on bespoke mesh
- * data (e.g. `TilesFadePlugin`, `DebugTilesPlugin`, GLTF Metadata extensions).
+ * @warn All tile geometry rendered with `BatchedMesh` will use the same material and only a single
+ * material map is supported. Only tile geometry containing a single mesh is supported. Not
+ * compatible with plugins that modify mesh materials or rely on bespoke mesh data (e.g.
+ * `TilesFadePlugin`, `DebugTilesPlugin`, GLTF Metadata extensions).
  * @param {Object} options
  * @param {WebGLRenderer} options.renderer The renderer used to generate a `WebGLArrayRenderTarget`.
  * @param {number} [options.instanceCount=500] Initial number of instances in the batched mesh.

src/three/renderer/tiles/TilesRenderer.js

@@ -42,8 +42,19 @@ function updateFrustumCulled( object, toInitialValue ) {
 
 }
 
+/**
+ * Three.js implementation of a 3D Tiles renderer. Extends `TilesRendererBase` with
+ * camera management, three.js scene integration, and GPU-accelerated tile loading.
+ * Add `tiles.group` to your scene and call `tiles.update()` each frame.
+ */
 export class TilesRenderer extends TilesRendererBase {
 
+	/**
+	 * If `true`, all tile meshes automatically have `frustumCulled` set to `false` since the
+	 * tiles renderer performs its own frustum culling. If `displayActiveTiles` is `true` or
+	 * multiple cameras are being used, consider setting this to `false`.
+	 * @type {boolean}
+	 */
 	get autoDisableRendererCulling() {
 
 		return this._autoDisableRendererCulling;
@@ -81,7 +92,21 @@ export class TilesRenderer extends TilesRendererBase {
 	constructor( ...args ) {
 
 		super( ...args );
+
+		/**
+		 * The container `Group` for the 3D tiles. Add this to the three.js scene. The group
+		 * also exposes a `matrixWorldInverse` field for transforming objects into the local
+		 * tileset frame.
+		 * @type {Group}
+		 */
 		this.group = new TilesGroup( this );
+
+		/**
+		 * The ellipsoid definition used for the tileset. Defaults to WGS84 and may be
+		 * overridden by the `3DTILES_ellipsoid` extension. Specified in the local frame of
+		 * `TilesRenderer.group`.
+		 * @type {Ellipsoid}
+		 */
 		this.ellipsoid = WGS84_ELLIPSOID.clone();
 		this.cameras = [];
 		this.cameraMap = new Map();
@@ -93,6 +118,10 @@ export class TilesRenderer extends TilesRendererBase {
 		// flag indicating whether frustum culling should be disabled
 		this._autoDisableRendererCulling = true;
 
+		/**
+		 * The `LoadingManager` used when loading tile geometry.
+		 * @type {LoadingManager}
+		 */
 		this.manager = new LoadingManager();
 
 		// saved for event dispatcher functions

utils/docs/RenderDocsUtils.js

@@ -1,3 +1,29 @@
+// Renders any @warn / @note custom tags from a doclet as GFM alert blocks.
+function renderAlertTags( doc ) {
+
+	const lines = [];
+	for ( const tag of ( doc.tags || [] ) ) {
+
+		if ( tag.title === 'warn' || tag.title === 'note' ) {
+
+			const type = tag.title === 'warn' ? 'WARN' : 'NOTE';
+			lines.push( `> [!${ type }]` );
+			for ( const line of tag.value.split( '\n' ) ) {
+
+				lines.push( `> ${ line }` );
+
+			}
+
+			lines.push( '' );
+
+		}
+
+	}
+
+	return lines.join( '\n' );
+
+}
+
 // Converts a heading name to its GitHub Markdown anchor id.
 export function toAnchor( name ) {
 
@@ -147,6 +173,8 @@ export function renderMember( doc, callbackMap = {} ) {
 
 	}
 
+	lines.push( renderAlertTags( doc ) );
+
 	return lines.join( '\n' );
 
 }
@@ -195,6 +223,8 @@ export function renderMethod( doc, callbackMap = {} ) {
 
 	}
 
+	lines.push( renderAlertTags( doc ) );
+
 	return lines.join( '\n' );
 
 }
@@ -256,6 +286,8 @@ export function renderTypedef( typeDoc, callbackMap = {}, resolveLink = null ) {
 
 	}
 
+	lines.push( renderAlertTags( typeDoc ) );
+
 	for ( const prop of ( typeDoc.properties || [] ) ) {
 
 		const type = formatType( prop.type, callbackMap );
@@ -421,6 +453,8 @@ export function renderClass( classDoc, members, callbackMap = {}, resolveLink =
 
 	}
 
+	lines.push( renderAlertTags( classDoc ) );
+
 	const visible = members.filter( m => m.access !== 'private' );
 	// Treat function doclets that carry an explicit @type tag as properties
 	// (e.g. arrow-function assignments like `this.schedulingCallback = func => ...`)