Skip to content

Commit b4437e5

Browse files
gkjohnsongkjohnson
authored
Docs: Migrate core/plugins to JSDoc (#1511)
* Update plugin jsdocs * Update docs * Lint fix * Update comments * Remove exported function
1 parent 65b5f9a commit b4437e5

10 files changed

Lines changed: 185 additions & 10 deletions

‎src/core/plugins/CesiumIonAuthPlugin.js‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,19 @@
11
import { CesiumIonAuth } from './auth/CesiumIonAuth.js';
22
import { GoogleCloudAuthPlugin } from './GoogleCloudAuthPlugin.js';
33

4+
/**
5+
* @callback AssetTypeHandlerCallback
6+
* @param {string} type - The Cesium Ion asset type (e.g. `'TERRAIN'`, `'GLTF'`, `'CZML'`).
7+
* @param {TilesRendererBase} tiles - The tiles renderer instance.
8+
* @param {Object} asset - The full asset endpoint JSON response.
9+
*/
10+
11+
/**
12+
* @classdesc
13+
* Plugin for authenticating requests to Cesium Ion. Handles token refresh, asset endpoint
14+
* resolution, and attribution collection. Automatically registers a GoogleCloudAuthPlugin
15+
* when the resolved asset is an external Google photorealistic tileset.
16+
*/
417
export class CesiumIonAuthPlugin {
518

619
get apiToken() {
@@ -27,6 +40,14 @@ export class CesiumIonAuthPlugin {
2740

2841
}
2942

43+
/**
44+
* @param {Object} options
45+
* @param {string} options.apiToken
46+
* @param {number|null} [options.assetId=null]
47+
* @param {boolean} [options.autoRefreshToken=false]
48+
* @param {boolean} [options.useRecommendedSettings=true]
49+
* @param {AssetTypeHandlerCallback} [options.assetTypeHandler]
50+
*/
3051
constructor( options = {} ) {
3152

3253
const {
@@ -44,10 +65,30 @@ export class CesiumIonAuthPlugin {
4465
this.name = 'CESIUM_ION_AUTH_PLUGIN';
4566
this.auth = new CesiumIonAuth( { apiToken, autoRefreshToken } );
4667

68+
/**
69+
* The Cesium Ion asset ID to load, or null if using an explicit root URL.
70+
* @type {number|null}
71+
*/
4772
this.assetId = assetId;
73+
/**
74+
* Whether to automatically refresh the token on 4xx errors.
75+
* @type {boolean}
76+
*/
4877
this.autoRefreshToken = autoRefreshToken;
78+
/**
79+
* Whether to apply recommended renderer settings for Cesium Ion assets.
80+
* @type {boolean}
81+
*/
4982
this.useRecommendedSettings = useRecommendedSettings;
83+
/**
84+
* Callback invoked when the resolved Cesium Ion asset type is not `3DTILES`.
85+
* @type {AssetTypeHandlerCallback}
86+
*/
5087
this.assetTypeHandler = assetTypeHandler;
88+
/**
89+
* The TilesRenderer instance this plugin is registered with.
90+
* @type {Object|null}
91+
*/
5192
this.tiles = null;
5293

5394
this._tileSetVersion = - 1;

‎src/core/plugins/EnforceNonZeroErrorPlugin.js‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,9 @@
1+
/**
2+
* @classdesc
3+
* Plugin that ensures every tile has a non-zero geometric error. Tiles with a geometric
4+
* error of zero are assigned a derived value based on the nearest ancestor with a non-zero
5+
* error, halved once per level of depth below that ancestor.
6+
*/
17
export class EnforceNonZeroErrorPlugin {
28

39
constructor() {

‎src/core/plugins/GoogleCloudAuthPlugin.js‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,22 @@ import { GoogleAttributionsManager } from './GoogleAttributionsManager.js';
33

44
const TILES_3D_API = 'https://tile.googleapis.com/v1/3dtiles/root.json';
55

6+
/**
7+
* @classdesc
8+
* Plugin for authenticating requests to the Google Cloud Maps APIs, including the
9+
* Photorealistic 3D Tiles and 2D Map Tiles APIs. Handles session-token management,
10+
* per-tile attribution collection, and optional logo attribution.
11+
*/
612
export class GoogleCloudAuthPlugin {
713

14+
/**
15+
* @param {Object} options
16+
* @param {string} options.apiToken
17+
* @param {Object|null} [options.sessionOptions=null]
18+
* @param {boolean} [options.autoRefreshToken=false]
19+
* @param {string|null} [options.logoUrl=null]
20+
* @param {boolean} [options.useRecommendedSettings=true]
21+
*/
822
constructor( {
923
apiToken,
1024
sessionOptions = null,
@@ -15,11 +29,27 @@ export class GoogleCloudAuthPlugin {
1529

1630
this.name = 'GOOGLE_CLOUD_AUTH_PLUGIN';
1731

32+
/**
33+
* The Google Cloud API key.
34+
* @type {string}
35+
*/
1836
this.apiToken = apiToken;
37+
/**
38+
* Whether to apply recommended renderer settings for photorealistic tiles.
39+
* @type {boolean}
40+
*/
1941
this.useRecommendedSettings = useRecommendedSettings;
42+
/**
43+
* URL of a logo image to include in attribution output, or null if not set.
44+
* @type {string|null}
45+
*/
2046
this.logoUrl = logoUrl;
2147

2248
this.auth = new GoogleCloudAuth( { apiToken, autoRefreshToken, sessionOptions } );
49+
/**
50+
* The TilesRenderer instance this plugin is registered with.
51+
* @type {Object|null}
52+
*/
2353
this.tiles = null;
2454

2555
this._visibilityChangeCallback = null;

‎src/core/plugins/ImplicitTilingPlugin.js‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,11 @@
11
import { SUBTREELoader } from './SUBTREELoader.js';
22

3+
/**
4+
* @classdesc
5+
* Plugin that adds support for 3D Tiles 1.1 implicit tiling. Intercepts tiles that carry
6+
* an `implicitTiling` field and expands them by loading and parsing `.subtree` files,
7+
* generating child tiles according to the implicit subdivision scheme.
8+
*/
39
export class ImplicitTilingPlugin {
410

511
constructor() {

‎src/core/plugins/SUBTREELoader.js‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -813,7 +813,7 @@ export class SUBTREELoader extends LoaderBase {
813813
*
814814
* @param {Object} subtree The subtree for looking up availability.
815815
* @param {Array} bottomRow The bottom row of tiles in a transcoded subtree.
816-
* @returns {[]} A list of identifiers for the child subtrees.
816+
* @returns {Array} A list of identifiers for the child subtrees.
817817
* @private
818818
*/
819819
listChildSubtrees( subtree, bottomRow ) {

‎src/core/plugins/auth/CesiumIonAuth.js‎

Lines changed: 23 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,33 @@
1-
// Class for making fetches to Cesium Ion, refreshing the token if needed.
1+
/**
2+
* @classdesc
3+
* Authentication helper for Cesium Ion. Fetches and caches a bearer token from the
4+
* Cesium Ion endpoint and injects it into outgoing requests. Supports optional
5+
* automatic token refresh on 4xx responses.
6+
*/
27
export class CesiumIonAuth {
38

9+
/**
10+
* @param {Object} [options={}]
11+
* @param {string} options.apiToken
12+
* @param {boolean} [options.autoRefreshToken=false]
13+
*/
414
constructor( options = {} ) {
515

616
const { apiToken, autoRefreshToken = false } = options;
17+
/**
18+
* The Cesium Ion access token.
19+
* @type {string}
20+
*/
721
this.apiToken = apiToken;
22+
/**
23+
* Whether to automatically refresh the token on 4xx errors.
24+
* @type {boolean}
25+
*/
826
this.autoRefreshToken = autoRefreshToken;
27+
/**
28+
* The endpoint URL used to fetch the bearer token.
29+
* @type {string|null}
30+
*/
931
this.authURL = null;
1032
this._tokenRefreshPromise = null;
1133
this._bearerToken = null;

‎src/core/plugins/auth/GoogleCloudAuth.js‎

Lines changed: 32 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,12 @@ import { TraversalUtils } from '3d-tiles-renderer/core';
22

33
const TILES_MAP_URL = 'https://tile.googleapis.com/v1/createSession';
44

5-
// Class for making fetches to Google Cloud, refreshing the token if needed.
6-
// Supports both the 2d map tiles API in addition to 3d tiles.
5+
/**
6+
* @classdesc
7+
* Authentication helper for Google Cloud Maps APIs. Manages session-token creation and
8+
* renewal for both the Photorealistic 3D Tiles API and the 2D Map Tiles API, injecting
9+
* the API key and session token into outgoing requests.
10+
*/
711
export class GoogleCloudAuth {
812

913
get isMapTilesSession() {
@@ -12,13 +16,39 @@ export class GoogleCloudAuth {
1216

1317
}
1418

19+
/**
20+
* @param {Object} [options={}]
21+
* @param {string} options.apiToken
22+
* @param {Object|null} [options.sessionOptions=null]
23+
* @param {boolean} [options.autoRefreshToken=false]
24+
*/
1525
constructor( options = {} ) {
1626

1727
const { apiToken, sessionOptions = null, autoRefreshToken = false } = options;
28+
/**
29+
* The Google Cloud API key.
30+
* @type {string}
31+
*/
1832
this.apiToken = apiToken;
33+
/**
34+
* Whether to automatically refresh the session token on 4xx errors.
35+
* @type {boolean}
36+
*/
1937
this.autoRefreshToken = autoRefreshToken;
38+
/**
39+
* The endpoint URL used to create or refresh the session token.
40+
* @type {string}
41+
*/
2042
this.authURL = TILES_MAP_URL;
43+
/**
44+
* The current session token, or null if not yet established.
45+
* @type {string|null}
46+
*/
2147
this.sessionToken = null;
48+
/**
49+
* Session options passed as the POST body when creating a Map Tiles session.
50+
* @type {Object|null}
51+
*/
2252
this.sessionOptions = sessionOptions;
2353
this._tokenRefreshPromise = null;
2454

‎src/core/plugins/loaders/QuantizedMeshLoaderBase.js‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,19 @@
11
import { LoaderBase } from '3d-tiles-renderer/core';
22

3-
export function zigZagDecode( value ) {
3+
function zigZagDecode( value ) {
44

55
return ( value >> 1 ) ^ ( - ( value & 1 ) );
66

77
}
88

9+
/**
10+
* @classdesc
11+
* Base loader for quantized-mesh terrain tiles. Parses the binary quantized-mesh format
12+
* into structured vertex, index, edge, and extension data. Sets the required `Accept`
13+
* header automatically. Subclasses should implement geometry construction from the
14+
* parsed result.
15+
* @augments LoaderBase
16+
*/
917
export class QuantizedMeshLoaderBase extends LoaderBase {
1018

1119
constructor( ...args ) {

‎utils/docs/RenderDocsUtils.js‎

Lines changed: 30 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,8 @@ function formatCallbackType( callbackDoc, callbackMap ) {
2020
? formatType( callbackDoc.returns[ 0 ].type, callbackMap )
2121
: 'void';
2222

23-
return `( ${ params.join( ', ' ) } ) => ${ ret }`;
23+
const sig = params.length > 0 ? ` ${ params.join( ', ' ) } ` : '';
24+
return `(${ sig }) => ${ ret }`;
2425

2526
}
2627

@@ -63,12 +64,36 @@ export function renderConstructor( classDoc, callbackMap = {} ) {
6364
const topLevel = ( classDoc.params || [] ).filter( p => ! p.name.includes( '.' ) );
6465
const options = ( classDoc.params || [] ).filter( p => p.name.includes( '.' ) );
6566

66-
const sig = topLevel.map( p => formatParam( p, callbackMap ) ).join( ', ' );
67+
// When there is exactly one top-level param and nested option fields, render the
68+
// options inline as a destructured object rather than as a separate bullet list.
69+
const isOptionsObject = topLevel.length === 1 && options.length > 0;
6770

6871
lines.push( '### .constructor' );
6972
lines.push( '' );
7073
lines.push( '```js' );
71-
lines.push( `constructor( ${ sig } )` );
74+
75+
if ( isOptionsObject ) {
76+
77+
lines.push( 'constructor( {' );
78+
for ( const param of options ) {
79+
80+
const name = param.name.split( '.' ).pop();
81+
const type = formatType( param.type, callbackMap );
82+
const defStr = param.defaultvalue !== undefined ? ` = ${ param.defaultvalue }` : '';
83+
const optional = param.optional && param.defaultvalue === undefined ? '?' : '';
84+
lines.push( `\t${ name }${ defStr }${ optional }: ${ type },` );
85+
86+
}
87+
88+
lines.push( '} )' );
89+
90+
} else {
91+
92+
const sig = topLevel.map( p => formatParam( p, callbackMap ) ).join( ', ' );
93+
lines.push( `constructor( ${ sig } )` );
94+
95+
}
96+
7297
lines.push( '```' );
7398
lines.push( '' );
7499

@@ -80,8 +105,8 @@ export function renderConstructor( classDoc, callbackMap = {} ) {
80105

81106
}
82107

83-
// Render nested options (e.g. options.layer, options.url) as a list
84-
if ( options.length > 0 ) {
108+
// Bullet list only used for the non-options-object case (e.g. mixed positional + nested params)
109+
if ( ! isOptionsObject && options.length > 0 ) {
85110

86111
for ( const param of options ) {
87112

‎utils/docs/build.js‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,13 @@ const ENTRY_POINTS = [
3636
'src/babylonjs/renderer',
3737
],
3838
},
39+
{
40+
output: 'src/core/plugins/API.md',
41+
title: '3d-tiles-renderer/core/plugins',
42+
sources: [
43+
'src/core/plugins',
44+
],
45+
},
3946
// {
4047
// output: 'src/r3f/API.md',
4148
// title: '3d-tiles-renderer/r3f',

0 commit comments

Comments
 (0)