Docs: More JSDoc. (#30719)

Author: Mugen87

examples/jsm/loaders/3DMLoader.js

@@ -30,12 +30,38 @@ import { EXRLoader } from '../loaders/EXRLoader.js';
 
 const _taskCache = new WeakMap();
 
+/**
+ * A loader for Rhinoceros 3D files and objects.
+ *
+ * Rhinoceros is a 3D modeler used to create, edit, analyze, document, render,
+ * animate, and translate NURBS curves, surfaces, breps, extrusions, point clouds,
+ * as well as polygon meshes and SubD objects. `rhino3dm.js` is compiled to WebAssembly
+ * from the open source geometry library `openNURBS`. The loader currently uses
+ * `rhino3dm.js 8.4.0`.
+ *
+ * ```js
+ * const loader = new Rhino3dmLoader();
+ * loader.setLibraryPath( 'https://cdn.jsdelivr.net/npm/[email protected]' );
+ *
+ * const object = await loader.loadAsync( 'models/3dm/Rhino_Logo.3dm' );
+ * scene.add( object );
+ * ```
+ *
+ * @augments Loader
+ */
 class Rhino3dmLoader extends Loader {
 
+	/**
+	 * Constructs a new Rhino 3DM loader.
+	 *
+	 * @param {LoadingManager} [manager] - The loading manager.
+	 */
 	constructor( manager ) {
 
 		super( manager );
 
+		// internals
+
 		this.libraryPath = '';
 		this.libraryPending = null;
 		this.libraryBinary = null;
@@ -54,6 +80,12 @@ class Rhino3dmLoader extends Loader {
 
 	}
 
+	/**
+	 * Path to a folder containing the JS and WASM libraries.
+	 *
+	 * @param {string} path - The library path to set.
+	 * @return {Rhino3dmLoader} A reference to this loader.
+	 */
 	setLibraryPath( path ) {
 
 		this.libraryPath = path;
@@ -62,6 +94,14 @@ class Rhino3dmLoader extends Loader {
 
 	}
 
+	/**
+	 * Sets the maximum number of Web Workers to be used during decoding.
+	 * A lower limit may be preferable if workers are also for other
+	 * tasks in the application.
+	 *
+	 * @param {number} workerLimit - The worker limit.
+	 * @return {Rhino3dmLoader} A reference to this loader.
+	 */
 	setWorkerLimit( workerLimit ) {
 
 		this.workerLimit = workerLimit;
@@ -70,6 +110,15 @@ class Rhino3dmLoader extends Loader {
 
 	}
 
+	/**
+	 * Starts loading from the given URL and passes the loaded 3DM asset
+	 * to the `onLoad()` callback.
+	 *
+	 * @param {string} url - The path/URL of the file to be loaded. This can also be a data URI.
+	 * @param {function(Object3D)} onLoad - Executed when the loading process has been finished.
+	 * @param {onProgressCallback} onProgress - Executed while the loading is in progress.
+	 * @param {onErrorCallback} onError - Executed when errors occur.
+	 */
 	load( url, onLoad, onProgress, onError ) {
 
 		const loader = new FileLoader( this.manager );
@@ -105,12 +154,22 @@ class Rhino3dmLoader extends Loader {
 
 	}
 
+	/**
+	 * Prints debug messages to the browser console.
+	 */
 	debug() {
 
 		console.log( 'Task load: ', this.workerPool.map( ( worker ) => worker._taskLoad ) );
 
 	}
 
+	/**
+	 * Decodes the 3DM asset data with a Web Worker.
+	 *
+	 * @param {ArrayBuffer} buffer - The raw 3DM asset data as an array buffer.
+	 * @param {string} url - The asset URL.
+	 * @return {Promise<Object3D>} A Promise that resolved with the decoded 3D object.
+	 */
 	decodeObjects( buffer, url ) {
 
 		let worker;
@@ -170,6 +229,14 @@ class Rhino3dmLoader extends Loader {
 
 	}
 
+	/**
+	 * Parses the given 3DM data and passes the loaded 3DM asset
+	 * to the `onLoad()` callback.
+	 *
+	 * @param {ArrayBuffer} data - The raw 3DM asset data as an array buffer.
+	 * @param {function(Object3D)} onLoad - Executed when the loading process has been finished.
+	 * @param {onErrorCallback} onError - Executed when errors occur.
+	 */
 	parse( data, onLoad, onError ) {
 
 		this.decodeObjects( data, '' )
@@ -962,6 +1029,10 @@ class Rhino3dmLoader extends Loader {
 
 	}
 
+	/**
+	 * Frees internal resources. This method should be called
+	 * when the loader is no longer required.
+	 */
 	dispose() {
 
 		for ( let i = 0; i < this.workerPool.length; ++ i ) {
@@ -972,8 +1043,6 @@ class Rhino3dmLoader extends Loader {
 
 		this.workerPool.length = 0;
 
-		return this;
-
 	}
 
 }

examples/jsm/loaders/3MFLoader.js

@@ -24,8 +24,7 @@ import * as fflate from '../libs/fflate.module.js';
 const COLOR_SPACE_3MF = SRGBColorSpace;
 
 /**
- *
- * 3D Manufacturing Format (3MF) specification: https://3mf.io/specification/
+ * A loader for the [3D Manufacturing Format (3MF)]{@link https://3mf.io/specification/} format.
  *
  * The following features from the core specification are supported:
  *
@@ -39,18 +38,46 @@ const COLOR_SPACE_3MF = SRGBColorSpace;
  * - Texture 2D Groups
  * - Color Groups (Vertex Colors)
  * - Metallic Display Properties (PBR)
+ *
+ * ```js
+ * const loader = new ThreeMFLoader();
+ *
+ * const object = await loader.loadAsync( './models/3mf/truck.3mf' );
+ * object.rotation.set( - Math.PI / 2, 0, 0 ); // z-up conversion
+ * scene.add( object );
+ * ```
+ *
+ * @augments Loader
  */
-
 class ThreeMFLoader extends Loader {
 
+	/**
+	 * Constructs a new 3MF loader.
+	 *
+	 * @param {LoadingManager} [manager] - The loading manager.
+	 */
 	constructor( manager ) {
 
 		super( manager );
 
+		/**
+		 * An array of available extensions.
+		 *
+		 * @type {Array<Object>}
+		 */
 		this.availableExtensions = [];
 
 	}
 
+	/**
+	 * Starts loading from the given URL and passes the loaded 3MF asset
+	 * to the `onLoad()` callback.
+	 *
+	 * @param {string} url - The path/URL of the file to be loaded. This can also be a data URI.
+	 * @param {function(Group)} onLoad - Executed when the loading process has been finished.
+	 * @param {onProgressCallback} onProgress - Executed while the loading is in progress.
+	 * @param {onErrorCallback} onError - Executed when errors occur.
+	 */
 	load( url, onLoad, onProgress, onError ) {
 
 		const scope = this;
@@ -85,6 +112,12 @@ class ThreeMFLoader extends Loader {
 
 	}
 
+	/**
+	 * Parses the given 3MF data and returns the resulting group.
+	 *
+	 * @param {ArrayBuffer} data - The raw 3MF asset data as an array buffer.
+	 * @return {Group} A group representing the parsed asset.
+	 */
 	parse( data ) {
 
 		const scope = this;
@@ -1571,6 +1604,11 @@ class ThreeMFLoader extends Loader {
 
 	}
 
+	/**
+	 * Adds a 3MF extension.
+	 *
+	 * @param {Object} extension - The extension to add.
+	 */
 	addExtension( extension ) {
 
 		this.availableExtensions.push( extension );

examples/jsm/loaders/AMFLoader.js

@@ -11,29 +11,42 @@ import {
 import * as fflate from '../libs/fflate.module.js';
 
 /**
- * Description: Early release of an AMF Loader following the pattern of the
- * example loaders in the three.js project.
+ * A loader for the AMF format.
  *
- * Usage:
- *	const loader = new AMFLoader();
- *	loader.load('/path/to/project.amf', function(objecttree) {
- *		scene.add(objecttree);
- *	});
+ * The loader supports materials, color and ZIP compressed files.
+ * No constellation support (yet).
  *
- * Materials now supported, material colors supported
- * Zip support, requires fflate
- * No constellation support (yet)!
+ * ```js
+ * const loader = new AMFLoader();
  *
+ * const object = await loader.loadAsync( './models/amf/rook.amf' );
+ * scene.add( object );
+ * ```
+ *
+ * @augments Loader
  */
-
 class AMFLoader extends Loader {
 
+	/**
+	 * Constructs a new AMF loader.
+	 *
+	 * @param {LoadingManager} [manager] - The loading manager.
+	 */
 	constructor( manager ) {
 
 		super( manager );
 
 	}
 
+	/**
+	 * Starts loading from the given URL and passes the loaded AMF asset
+	 * to the `onLoad()` callback.
+	 *
+	 * @param {string} url - The path/URL of the file to be loaded. This can also be a data URI.
+	 * @param {function(Group)} onLoad - Executed when the loading process has been finished.
+	 * @param {onProgressCallback} onProgress - Executed while the loading is in progress.
+	 * @param {onErrorCallback} onError - Executed when errors occur.
+	 */
 	load( url, onLoad, onProgress, onError ) {
 
 		const scope = this;
@@ -69,6 +82,12 @@ class AMFLoader extends Loader {
 
 	}
 
+	/**
+	 * Parses the given AMF data and returns the resulting group.
+	 *
+	 * @param {ArrayBuffer} data - The raw AMF asset data as an array buffer.
+	 * @return {Group} A group representing the parsed asset.
+	 */
 	parse( data ) {
 
 		function loadDocument( data ) {

examples/jsm/loaders/BVHLoader.js

@@ -11,23 +11,65 @@ import {
 } from 'three';
 
 /**
- * Description: reads BVH files and outputs a single Skeleton and an AnimationClip
+ * A loader for the BVH format.
  *
- * Currently only supports bvh files containing a single root.
+ * Imports BVH files and outputs a single {@link Skeleton} and {@link AnimationClip}.
+ * The loader only supports BVH files containing a single root right now.
  *
+ * ```js
+ * const loader = new BVHLoader();
+ * const result = await loader.loadAsync( 'models/bvh/pirouette.bvh' );
+ *
+ * // visualize skeleton
+ * const skeletonHelper = new THREE.SkeletonHelper( result.skeleton.bones[ 0 ] );
+ * scene.add( result.skeleton.bones[ 0 ] );
+ * scene.add( skeletonHelper );
+ *
+ * // play animation clip
+ * mixer = new THREE.AnimationMixer( result.skeleton.bones[ 0 ] );
+ * mixer.clipAction( result.clip ).play();
+ * ```
+ *
+ * @augments Loader
  */
-
 class BVHLoader extends Loader {
 
+	/**
+	 * Constructs a new BVH loader.
+	 *
+	 * @param {LoadingManager} [manager] - The loading manager.
+	 */
 	constructor( manager ) {
 
 		super( manager );
 
+		/**
+		 * Whether to animate bone positions or not.
+		 *
+		 * @type {boolean}
+		 * @default true
+		 */
 		this.animateBonePositions = true;
+
+		/**
+		 * Whether to animate bone rotations or not.
+		 *
+		 * @type {boolean}
+		 * @default true
+		 */
 		this.animateBoneRotations = true;
 
 	}
 
+	/**
+	 * Starts loading from the given URL and passes the loaded BVH asset
+	 * to the `onLoad()` callback.
+	 *
+	 * @param {string} url - The path/URL of the file to be loaded. This can also be a data URI.
+	 * @param {function({skeleton:Skeleton,clip:AnimationClip})} onLoad - Executed when the loading process has been finished.
+	 * @param {onProgressCallback} onProgress - Executed while the loading is in progress.
+	 * @param {onErrorCallback} onError - Executed when errors occur.
+	 */
 	load( url, onLoad, onProgress, onError ) {
 
 		const scope = this;
@@ -62,15 +104,19 @@ class BVHLoader extends Loader {
 
 	}
 
+	/**
+	 * Parses the given BVH data and returns the resulting data.
+	 *
+	 * @param {string} text - The raw BVH data as a string.
+	 * @return {{skeleton:Skeleton,clip:AnimationClip}} An object representing the parsed asset.
+	 */
 	parse( text ) {
 
-		/*
-			reads a string array (lines) from a BVH file
-			and outputs a skeleton structure including motion data
+		// reads a string array (lines) from a BVH file
+		// and outputs a skeleton structure including motion data
 
-			returns thee root node:
-			{ name: '', channels: [], children: [] }
-		*/
+		// returns thee root node:
+		// { name: '', channels: [], children: [] }
 		function readBvh( lines ) {
 
 			// read model structure