@s-rigaud Do you have an idea how we can rewrite this so we have a single type definition an refer to it just once. Something like:

@type {BlendingTypes}

I've struggled with such enum-like definitions for quite a while with JSDoc. I know there is the () syntax that you can use the restrict the usage on the values inside the parenthesis. But in our case we need to define NoBlending first and then a collection of all blending types.

I think something like NoBlending should be documented as a global.

But then there is still the question if we could group some globals into a type.

I'm aware of limitations of Jsdoc regarding enums and tuples in general. Most of the time I end up with some workaround implying some TS.

Base on this answer and the struggle of just using enum I think we will have to also find a workaround for those values.

The best approach I got is to define a type and to document each possible values as properties (the semantic is not really suited as the @property keyword should be used for the key of an object and not a fake enum but it is the best output documentation I manage to generate for now). I end up with a "coherent" documentation from a user point of view:

/**
 * @typedef {number} BlendingType
 * @property {number} NoBlending 0
 * @property {number} NormalBlending 1
 **/

Would that also work in context of auto-completion in editors? I could expect a tool could complain when doing the following...

material.blending = NoBlending;

...since NoBlending is not of type BlendingType. It is a property of the type and that seems to be a mismatch.

Well they won't complain if they are based on the JsDoc because all the types in @type {(NoBlending|NormalBlending|AdditiveBlending|SubtractiveBlending|MultiplyBlending|CustomBlending)} are already undfined and being evaluated to any. The only way to be more precise is to use the number type but then you lose all the accepted values. We could put all the valid integer values but it's not really maintainable. I am not aware of a nice solution to handle this case :/

because all the types in @type {(NoBlending|NormalBlending|AdditiveBlending|SubtractiveBlending|MultiplyBlending|CustomBlending)} are already undfined and being evaluated to any.

It seems when actually documenting the globals, this issue resolves. E.g. when documenting ClampToEdgeWrapping in src/constants.js like so:

/**
 * The last pixel of the texture stretches to the edge of the mesh.
 *
 * @constant
 * @type {number}
 */
export const ClampToEdgeWrapping = 1001;

The ClampToEdgeWrapping references in the docs are now links and refer to the correct global.

From Texture.html docs:

From global.html:

Let's start with this approach and see how it goes.

Nice ! Do you think it worth documenting the value as well ? Currently nothing is shown about it 🤔

The value of such constants does usually not matter.