Docs: More JSDoc. (#30651)

Author: Mugen87

Diff for: docs/examples/en/geometries/ParametricGeometry.html

@@ -29,7 +29,7 @@ <h2>Import</h2>
 		<h2>Code Example</h2>
 
 		<code>
-		const geometry = new THREE.ParametricGeometry( THREE.ParametricGeometries.klein, 25, 25 );
+		const geometry = new THREE.ParametricGeometry( klein, 25, 25 );
 		const material = new THREE.MeshBasicMaterial( { color: 0x00ff00 } );
 		const klein = new THREE.Mesh( geometry, material );
 		scene.add( klein );

Diff for: docs/examples/zh/geometries/ParametricGeometry.html

@@ -27,7 +27,7 @@ <h2>导入</h2>
 		<h2>代码示例</h2>
 
 		<code>
-		const geometry = new THREE.ParametricGeometry( THREE.ParametricGeometries.klein, 25, 25 );
+		const geometry = new THREE.ParametricGeometry( klein, 25, 25 );
 		const material = new THREE.MeshBasicMaterial( { color: 0x00ff00 } );
 		const klein = new THREE.Mesh( geometry, material );
 		scene.add( klein );

Diff for: examples/jsm/Addons.js

@@ -46,7 +46,7 @@ export * from './exporters/USDZExporter.js';
 export * from './geometries/BoxLineGeometry.js';
 export * from './geometries/ConvexGeometry.js';
 export * from './geometries/DecalGeometry.js';
-export * from './geometries/ParametricGeometries.js';
+export * from './geometries/ParametricFunctions.js';
 export * from './geometries/ParametricGeometry.js';
 export * from './geometries/RoundedBoxGeometry.js';
 export * from './geometries/TeapotGeometry.js';

Diff for: examples/jsm/geometries/BoxLineGeometry.js

@@ -3,8 +3,30 @@ import {
 	Float32BufferAttribute
 } from 'three';
 
+/**
+ * A special type of box geometry intended for {@link LineSegments}.
+ *
+ * ```js
+ * const geometry = new THREE.BoxLineGeometry();
+ * const material = new THREE.LineBasicMaterial( { color: 0x00ff00 } );
+ * const lines = new THREE.LineSegments( geometry, material );
+ * scene.add( lines );
+ * ```
+ *
+ * @augments BufferGeometry
+ */
 class BoxLineGeometry extends BufferGeometry {
 
+	/**
+	 * Constructs a new box line geometry.
+	 *
+	 * @param {number} [width=1] - The width. That is, the length of the edges parallel to the X axis.
+	 * @param {number} [height=1] - The height. That is, the length of the edges parallel to the Y axis.
+	 * @param {number} [depth=1] - The depth. That is, the length of the edges parallel to the Z axis.
+	 * @param {number} [widthSegments=1] - Number of segmented rectangular sections along the width of the sides.
+	 * @param {number} [heightSegments=1] - Number of segmented rectangular sections along the height of the sides.
+	 * @param {number} [depthSegments=1] - Number of segmented rectangular sections along the depth of the sides.
+	 */
 	constructor( width = 1, height = 1, depth = 1, widthSegments = 1, heightSegments = 1, depthSegments = 1 ) {
 
 		super();

Diff for: examples/jsm/geometries/ConvexGeometry.js

@@ -4,8 +4,26 @@ import {
 } from 'three';
 import { ConvexHull } from '../math/ConvexHull.js';
 
+/**
+ * This class can be used to generate a convex hull for a given array of 3D points.
+ * The average time complexity for this task is considered to be O(nlog(n)).
+ *
+ * ```js
+ * const geometry = new ConvexGeometry( points );
+ * const material = new THREE.MeshBasicMaterial( { color: 0x00ff00 } );
+ * const mesh = new THREE.Mesh( geometry, material );
+ * scene.add( mesh );
+ * ```
+ *
+ * @augments BufferGeometry
+ */
 class ConvexGeometry extends BufferGeometry {
 
+	/**
+	 * Constructs a new convex geometry.
+	 *
+	 * @param {Array<Vector3>} points - An array of points in 3D space which should be enclosed by the convex hull.
+	 */
 	constructor( points = [] ) {
 
 		super();

Diff for: examples/jsm/geometries/DecalGeometry.js

@@ -9,22 +9,33 @@ import {
 } from 'three';
 
 /**
- * You can use this geometry to create a decal mesh, that serves different kinds of purposes.
- * e.g. adding unique details to models, performing dynamic visual environmental changes or covering seams.
+ * This class can be used to create a decal mesh that serves different kinds of purposes e.g.
+ * adding unique details to models, performing dynamic visual environmental changes or covering seams.
  *
- * Constructor parameter:
+ * Please not that decal projections can be distored when used around corners. More information at
+ * this GitHub issue: [Decal projections without distortions]{@link https://github.com/mrdoob/three.js/issues/21187}.
  *
- * mesh — Any mesh object
- * position — Position of the decal projector
- * orientation — Orientation of the decal projector
- * size — Size of the decal projector
+ * Reference: [How to project decals]{@link http://blog.wolfire.com/2009/06/how-to-project-decals/}
  *
- * reference: http://blog.wolfire.com/2009/06/how-to-project-decals/
+ * ```js
+ * const geometry = new DecalGeometry( mesh, position, orientation, size );
+ * const material = new THREE.MeshBasicMaterial( { color: 0x00ff00 } );
+ * const mesh = new THREE.Mesh( geometry, material );
+ * scene.add( mesh );
+ * ```
  *
+ * @augments BufferGeometry
  */
-
 class DecalGeometry extends BufferGeometry {
 
+	/**
+	 * Constructs a new decal geometry.
+	 *
+	 * @param {Mesh} [mesh] - The base mesh the decal should be projected on.
+	 * @param {Vector3} [position] - The position of the decal projector.
+	 * @param {Euler} [orientation] - The orientation of the decal projector.
+	 * @param {Vector3} [size] - Tje scale of the decal projector.
+	 */
 	constructor( mesh = new Mesh(), position = new Vector3(), orientation = new Euler(), size = new Vector3( 1, 1, 1 ) ) {
 
 		super();

Diff for: examples/jsm/geometries/ParametricFunctions.js

@@ -0,0 +1,97 @@
+
+/** @module ParametricFunctions */
+
+/**
+ * A parametric function representing the Klein bottle.
+ *
+ * @param {number} v - The `v` coordinate on the surface in the range `[0,1]`.
+ * @param {number} u - The `u` coordinate on the surface in the range `[0,1]`.
+ * @param {Vector3} target - The target vector that is used to store the method's result.
+ */
+function klein( v, u, target ) {
+
+	u *= Math.PI;
+	v *= 2 * Math.PI;
+
+	u = u * 2;
+	let x, z;
+	if ( u < Math.PI ) {
+
+		x = 3 * Math.cos( u ) * ( 1 + Math.sin( u ) ) + ( 2 * ( 1 - Math.cos( u ) / 2 ) ) * Math.cos( u ) * Math.cos( v );
+		z = - 8 * Math.sin( u ) - 2 * ( 1 - Math.cos( u ) / 2 ) * Math.sin( u ) * Math.cos( v );
+
+	} else {
+
+		x = 3 * Math.cos( u ) * ( 1 + Math.sin( u ) ) + ( 2 * ( 1 - Math.cos( u ) / 2 ) ) * Math.cos( v + Math.PI );
+		z = - 8 * Math.sin( u );
+
+	}
+
+	const y = - 2 * ( 1 - Math.cos( u ) / 2 ) * Math.sin( v );
+
+	target.set( x, y, z );
+
+}
+
+/**
+ * A parametric function representing a flat plane.
+ *
+ * @param {number} u - The `u` coordinate on the surface in the range `[0,1]`.
+ * @param {number} v - The `v` coordinate on the surface in the range `[0,1]`.
+ * @param {Vector3} target - The target vector that is used to store the method's result.
+ */
+function plane( u, v, target ) {
+
+	target.set( u, 0, v );
+
+}
+
+/**
+ * A parametric function representing a flat mobius strip.
+ *
+ * @param {number} u - The `u` coordinate on the surface in the range `[0,1]`.
+ * @param {number} t - The `v` coordinate on the surface in the range `[0,1]`.
+ * @param {Vector3} target - The target vector that is used to store the method's result.
+ */
+function mobius( u, t, target ) {
+
+	// http://www.wolframalpha.com/input/?i=M%C3%B6bius+strip+parametric+equations&lk=1&a=ClashPrefs_*Surface.MoebiusStrip.SurfaceProperty.ParametricEquations-
+	u = u - 0.5;
+	const v = 2 * Math.PI * t;
+
+	const a = 2;
+
+	const x = Math.cos( v ) * ( a + u * Math.cos( v / 2 ) );
+	const y = Math.sin( v ) * ( a + u * Math.cos( v / 2 ) );
+	const z = u * Math.sin( v / 2 );
+
+	target.set( x, y, z );
+
+}
+
+/**
+ * A parametric function representing a volumetric mobius strip.
+ *
+ * @param {number} u - The `u` coordinate on the surface in the range `[0,1]`.
+ * @param {number} t - The `v` coordinate on the surface in the range `[0,1]`.
+ * @param {Vector3} target - The target vector that is used to store the method's result.
+ */
+function mobius3d( u, t, target ) {
+
+	u *= Math.PI;
+	t *= 2 * Math.PI;
+
+	u = u * 2;
+	const phi = u / 2;
+	const major = 2.25, a = 0.125, b = 0.65;
+
+	let x = a * Math.cos( t ) * Math.cos( phi ) - b * Math.sin( t ) * Math.sin( phi );
+	const z = a * Math.cos( t ) * Math.sin( phi ) + b * Math.sin( t ) * Math.cos( phi );
+	const y = ( major + x ) * Math.sin( u );
+	x = ( major + x ) * Math.cos( u );
+
+	target.set( x, y, z );
+
+}
+
+export { klein, plane, mobius, mobius3d };