Skip to content

Commit

Permalink
Eslint: enforce valid JSdoc format
Browse files Browse the repository at this point in the history
  • Loading branch information
Samuel Rigaud committed Dec 9, 2024
1 parent 1fc010c commit fdb317c
Show file tree
Hide file tree
Showing 25 changed files with 114 additions and 28 deletions.
10 changes: 10 additions & 0 deletions .eslintrc.json
Original file line number Diff line number Diff line change
Expand Up @@ -63,6 +63,16 @@
],
"no-duplicate-imports": [
"error"
],
"valid-jsdoc": [
"error",
{
"requireReturn": false,
"requireReturnType": true,
"requireParamDescription": false,
"requireReturnDescription": false,
"requireParamType": true
}
]
}
}
20 changes: 18 additions & 2 deletions src/cameras/PerspectiveCamera.js
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,7 @@ class PerspectiveCamera extends Camera {
* The default film gauge is 35, so that the focal length can be specified for
* a 35mm (full frame) camera.
*
* Values for focal length and film gauge must have the same unit.
* @param {number} focalLength - Values for focal length and film gauge must have the same unit.
*/
setFocalLength( focalLength ) {

Expand All @@ -76,6 +76,8 @@ class PerspectiveCamera extends Camera {

/**
* Calculates the focal length from the current .fov and .filmGauge.
*
* @returns {number}
*/
getFocalLength() {

Expand Down Expand Up @@ -109,6 +111,10 @@ class PerspectiveCamera extends Camera {
/**
* Computes the 2D bounds of the camera's viewable rectangle at a given distance along the viewing direction.
* Sets minTarget and maxTarget to the coordinates of the lower-left and upper-right corners of the view rectangle.
*
* @param {number} distance
* @param {number} minTarget
* @param {number} maxTarget
*/
getViewBounds( distance, minTarget, maxTarget ) {

Expand All @@ -124,7 +130,10 @@ class PerspectiveCamera extends Camera {

/**
* Computes the width and height of the camera's viewable rectangle at a given distance along the viewing direction.
* Copies the result into the target Vector2, where x is width and y is height.
*
* @param {number} distance
* @param {Vector2} target - Vector2 target used to store result where x is width and y is height.
* @returns {Vector2}
*/
getViewSize( distance, target ) {

Expand Down Expand Up @@ -168,6 +177,13 @@ class PerspectiveCamera extends Camera {
* camera.setViewOffset( fullWidth, fullHeight, w * 2, h * 1, w, h );
*
* Note there is no reason monitors have to be the same size or in a grid.
*
* @param {number} fullWidth
* @param {number} fullHeight
* @param {number} x
* @param {number} y
* @param {number} width
* @param {number} height
*/
setViewOffset( fullWidth, fullHeight, x, y, width, height ) {

Expand Down
20 changes: 20 additions & 0 deletions src/extras/PMREMGenerator.js
Original file line number Diff line number Diff line change
Expand Up @@ -102,6 +102,12 @@ class PMREMGenerator {
* in radians to be applied to the scene before PMREM generation. Optional near
* and far planes ensure the scene is rendered in its entirety (the cubeCamera
* is placed at the origin).
*
* @param {Scene} scene
* @param {number} sigma
* @param {number} near
* @param {number} far
* @return {WebGLRenderTarget}
*/
fromScene( scene, sigma = 0, near = 0.1, far = 100 ) {

Expand Down Expand Up @@ -137,6 +143,10 @@ class PMREMGenerator {
* or HDR. The ideal input image size is 1k (1024 x 512),
* as this matches best with the 256 x 256 cubemap output.
* The smallest supported equirectangular image size is 64 x 32.
*
* @param {Texture} equirectangular
* @param {WebGLRenderTarget} [renderTarget=null] - Optional render target.
* @return {WebGLRenderTarget}
*/
fromEquirectangular( equirectangular, renderTarget = null ) {

Expand All @@ -149,6 +159,10 @@ class PMREMGenerator {
* or HDR. The ideal input cube size is 256 x 256,
* as this matches best with the 256 x 256 cubemap output.
* The smallest supported cube size is 16 x 16.
*
* @param {Texture} cubemap
* @param {null} [renderTarget=null] - Optional render target.
* @return {WebGLRenderTarget}
*/
fromCubemap( cubemap, renderTarget = null ) {

Expand Down Expand Up @@ -466,6 +480,12 @@ class PMREMGenerator {
* the blur latitudinally (around the poles), and then longitudinally (towards
* the poles) to approximate the orthogonally-separable blur. It is least
* accurate at the poles, but still does a decent job.
*
* @param {WebGLRenderTarget} cubeUVRenderTarget
* @param {number} lodIn
* @param {number} lodOut
* @param {number} sigma
* @param {Vector3} [poleAxis]
*/
_blur( cubeUVRenderTarget, lodIn, lodOut, sigma, poleAxis ) {

Expand Down
6 changes: 6 additions & 0 deletions src/extras/TextureUtils.js
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,12 @@ function fill( texture ) {
/**
* Given the width, height, format, and type of a texture. Determines how many
* bytes must be used to represent the texture.
*
* @param {Number} width
* @param {Number} height
* @param {Number} format
* @param {Number} type
* @return {Number} The number of bytes required to represent the texture.
*/
function getByteLength( width, height, format, type ) {

Expand Down
2 changes: 1 addition & 1 deletion src/nodes/code/ExpressionNode.js
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ class ExpressionNode extends Node {
* Constructs a new expression node.
*
* @param {String} [snippet=''] - The native code snippet.
* @param {String} [includes='void'] - The node type.
* @param {String} [nodeType='void'] - The node type.
*/
constructor( snippet = '', nodeType = 'void' ) {

Expand Down
2 changes: 1 addition & 1 deletion src/nodes/core/IndexNode.js
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ class IndexNode extends Node {
/**
* Constructs a new index node.
*
* @param {('vertex'|'instance'|'subgroup'|'invocationLocal'|'invocationSubgroup'|'draw')} value - The scope of the index node.
* @param {('vertex'|'instance'|'subgroup'|'invocationLocal'|'invocationSubgroup'|'draw')} scope - The scope of the index node.
*/
constructor( scope ) {

Expand Down
4 changes: 4 additions & 0 deletions src/nodes/core/Node.js
Original file line number Diff line number Diff line change
Expand Up @@ -125,6 +125,7 @@ class Node extends EventDispatcher {
*
* @type {Boolean}
* @default false
* @param {boolean} value
*/
set needsUpdate( value ) {

Expand Down Expand Up @@ -532,6 +533,7 @@ class Node extends EventDispatcher {
* The method can be implemented to update the node's internal state before it is used to render an object.
* The {@link Node#updateBeforeType} property defines how often the update is executed.
*
* @abstract
* @param {NodeFrame} frame - A reference to the current node frame.
* @return {Boolean?} An optional bool that indicates whether the implementation actually performed an update or not (e.g. due to caching).
*/
Expand All @@ -545,6 +547,7 @@ class Node extends EventDispatcher {
* The method can be implemented to update the node's internal state after it was used to render an object.
* The {@link Node#updateAfterType} property defines how often the update is executed.
*
* @abstract
* @param {NodeFrame} frame - A reference to the current node frame.
* @return {Boolean?} An optional bool that indicates whether the implementation actually performed an update or not (e.g. due to caching).
*/
Expand All @@ -558,6 +561,7 @@ class Node extends EventDispatcher {
* The method can be implemented to update the node's internal state when it is used to render an object.
* The {@link Node#updateType} property defines how often the update is executed.
*
* @abstract
* @param {NodeFrame} frame - A reference to the current node frame.
* @return {Boolean?} An optional bool that indicates whether the implementation actually performed an update or not (e.g. due to caching).
*/
Expand Down
10 changes: 5 additions & 5 deletions src/nodes/core/NodeBuilder.js
Original file line number Diff line number Diff line change
Expand Up @@ -797,7 +797,7 @@ class NodeBuilder {
* resolved to `textureSize` in GLSL.
*
* @abstract
* @param {String} name - The method name to resolve.
* @param {String} method - The method name to resolve.
* @return {String} The resolved method name.
*/
getMethod( method ) {
Expand Down Expand Up @@ -896,7 +896,7 @@ class NodeBuilder {
/**
* Returns a cache for the given node.
*
* @param {Node} Node - The node.
* @param {Node} node - The node.
* @param {Boolean} [parent=true] - Whether this node refers to a shared parent cache or not.
* @return {NodeCache} The cache.
*/
Expand Down Expand Up @@ -999,7 +999,7 @@ class NodeBuilder {
/**
* Calling this method increases the usage count for the given node by one.
*
* @param {Node} Node - The node to increase the usage count for.
* @param {Node} node - The node to increase the usage count for.
* @return {Number} The updated usage count.
*/
increaseUsage( node ) {
Expand Down Expand Up @@ -1319,7 +1319,7 @@ class NodeBuilder {
/**
* Returns the type for a given typed array.
*
* @param {TypedArray} type - The typed array.
* @param {TypedArray} array - The typed array.
* @return {String} The type.
*/
getTypeFromArray( array ) {
Expand Down Expand Up @@ -1871,7 +1871,7 @@ class NodeBuilder {
/**
* Generates a code flow based on a TSL function: Fn().
*
* @param {ShaderNodeInternal} node - A function code will be generated based on the input.
* @param {ShaderNodeInternal} shaderNode - A function code will be generated based on the input.
* @return {Object}
*/
flowShaderNode( shaderNode ) {
Expand Down
3 changes: 2 additions & 1 deletion src/nodes/core/TempNode.js
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ class TempNode extends Node {
/**
* Constructs a temp node.
*
* @param {String} nodeType - The node type.
* @param {String} type - The node type.
*/
constructor( type ) {

Expand All @@ -39,6 +39,7 @@ class TempNode extends Node {
/**
* Whether this node is used more than once in context of other nodes.
*
* @param {NodeBuilder} builder - The node builder.
* @return {Boolean} A flag that indicates if there is more than one dependency to other nodes.
*/
hasDependencies( builder ) {
Expand Down
2 changes: 1 addition & 1 deletion src/nodes/display/NormalMapNode.js
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ class NormalMapNode extends TempNode {
/**
* Constructs a new normal map node.
*
* @param {Node} textureNode - Represents the normal map data.
* @param {Node} node - Represents the normal map data.
* @param {Node?} [scaleNode=null] - Controls the intensity of the effect.
*/
constructor( node, scaleNode = null ) {
Expand Down
1 change: 0 additions & 1 deletion src/nodes/display/ScreenNode.js
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,6 @@ class ScreenNode extends Node {
* from the current renderer.
*
* @param {NodeFrame} frame - A reference to the current node frame.
* @return {Boolean?} An optional bool that indicates whether the implementation actually performed an update or not (e.g. due to caching).
*/
update( { renderer } ) {

Expand Down
4 changes: 2 additions & 2 deletions src/nodes/functions/BasicLightingModel.js
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ class BasicLightingModel extends LightingModel {
/**
* Implements the baked indirect lighting with its modulation.
*
* @param {ContextNode} input - The current node context.
* @param {ContextNode} context - The current node context.
* @param {StackNode} stack - The current stack.
* @param {NodeBuilder} builder - The current node builder.
*/
Expand Down Expand Up @@ -61,7 +61,7 @@ class BasicLightingModel extends LightingModel {
/**
* Implements the environment mapping.
*
* @param {ContextNode} input - The current node context.
* @param {ContextNode} context - The current node context.
* @param {StackNode} stack - The current stack.
* @param {NodeBuilder} builder - The current node builder.
*/
Expand Down
6 changes: 3 additions & 3 deletions src/nodes/functions/PhysicalLightingModel.js
Original file line number Diff line number Diff line change
Expand Up @@ -473,7 +473,7 @@ class PhysicalLightingModel extends LightingModel {
* Depending on what features are requested, the method prepares certain node variables
* which are later used for lighting computations.
*
* @param {ContextNode} input - The current node context.
* @param {ContextNode} context - The current node context.
*/
start( context ) {

Expand Down Expand Up @@ -641,7 +641,7 @@ class PhysicalLightingModel extends LightingModel {
/**
* Implements the indirect lighting.
*
* @param {ContextNode} input - The current node context.
* @param {ContextNode} context - The current node context.
* @param {StackNode} stack - The current stack.
* @param {NodeBuilder} builder - The current node builder.
*/
Expand Down Expand Up @@ -758,7 +758,7 @@ class PhysicalLightingModel extends LightingModel {
/**
* Used for final lighting accumulations depending on the requested features.
*
* @param {ContextNode} input - The current node context.
* @param {ContextNode} context - The current node context.
* @param {StackNode} stack - The current stack.
* @param {NodeBuilder} builder - The current node builder.
*/
Expand Down
2 changes: 1 addition & 1 deletion src/nodes/functions/ShadowMaskModel.js
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ class ShadowMaskModel extends LightingModel {
/**
* Uses the shadow mask to produce the final color.
*
* @param {ContextNode} input - The current node context.
* @param {ContextNode} context - The current node context.
*/
finish( context ) {

Expand Down
1 change: 1 addition & 0 deletions src/nodes/geometry/RangeNode.js
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,7 @@ class RangeNode extends Node {
/**
* Returns the vector length which is computed based on the range definition.
*
* @param {NodeBuilder} builder - The current node builder.
* @return {Number} The vector length.
*/
getVectorLength( builder ) {
Expand Down
2 changes: 2 additions & 0 deletions src/nodes/lighting/PointLightNode.js
Original file line number Diff line number Diff line change
Expand Up @@ -90,6 +90,8 @@ class PointLightNode extends AnalyticLightNode {

/**
* Overwritten to setup point light specific shadow.
*
* @return {PointShadowNode}
*/
setupShadowNode() {

Expand Down
3 changes: 2 additions & 1 deletion src/nodes/pmrem/PMREMNode.js
Original file line number Diff line number Diff line change
Expand Up @@ -107,7 +107,7 @@ class PMREMNode extends TempNode {
/**
* Constructs a new function overloading node.
*
* @param {Texture} texture - The input texture.
* @param {Texture} value - The input texture.
* @param {Node<vec2>} [uvNode=null] - The uv node.
* @param {Node<float>} [levelNode=null] - The level node.
*/
Expand Down Expand Up @@ -203,6 +203,7 @@ class PMREMNode extends TempNode {
/**
* The node's texture value.
*
* @param {Texture} value
* @type {Texture}
*/
set value( value ) {
Expand Down
2 changes: 1 addition & 1 deletion src/nodes/utils/MaxMipLevelNode.js
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,7 @@ class MaxMipLevelNode extends UniformNode {
/**
* Constructs a new max mip level node.
*
* @param {TextureNode} node - The texture node to compute the max mip level for.
* @param {TextureNode} textureNode - The texture node to compute the max mip level for.
*/
constructor( textureNode ) {

Expand Down
8 changes: 4 additions & 4 deletions src/nodes/utils/Oscillators.js
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ import { time } from './Timer.js';
* Generates a sine wave oscillation based on a timer.
*
* @method
* @param {Node<float>} time - The timer to generate the oscillation with.
* @param {Node<float>} t - The timer to generate the oscillation with.
* @return {Node<float>} The oscillation node.
*/
export const oscSine = ( t = time ) => t.add( 0.75 ).mul( Math.PI * 2 ).sin().mul( 0.5 ).add( 0.5 );
Expand All @@ -15,7 +15,7 @@ export const oscSine = ( t = time ) => t.add( 0.75 ).mul( Math.PI * 2 ).sin().mu
* Generates a square wave oscillation based on a timer.
*
* @method
* @param {Node<float>} time - The timer to generate the oscillation with.
* @param {Node<float>} t - The timer to generate the oscillation with.
* @return {Node<float>} The oscillation node.
*/
export const oscSquare = ( t = time ) => t.fract().round();
Expand All @@ -24,7 +24,7 @@ export const oscSquare = ( t = time ) => t.fract().round();
* Generates a triangle wave oscillation based on a timer.
*
* @method
* @param {Node<float>} time - The timer to generate the oscillation with.
* @param {Node<float>} t - The timer to generate the oscillation with.
* @return {Node<float>} The oscillation node.
*/
export const oscTriangle = ( t = time ) => t.add( 0.5 ).fract().mul( 2 ).sub( 1 ).abs();
Expand All @@ -33,7 +33,7 @@ export const oscTriangle = ( t = time ) => t.add( 0.5 ).fract().mul( 2 ).sub( 1
* Generates a sawtooth wave oscillation based on a timer.
*
* @method
* @param {Node<float>} time - The timer to generate the oscillation with.
* @param {Node<float>} t - The timer to generate the oscillation with.
* @return {Node<float>} The oscillation node.
*/
export const oscSawtooth = ( t = time ) => t.fract();
Loading

0 comments on commit fdb317c

Please sign in to comment.