Three.js: Add default values to TypeScript declaration files

[dmnsgn]

Description of the problem

Having definitions helps a lot but they are lacking the proper setting of the default value. It is usually in the comment just above each property so is there any blocker to include them as well.

See for instance:

https://github.com/mrdoob/three.js/blob/4a8c4ae51943f04ba94d04339e671bfe075c41ca/src/renderers/WebGLRenderer.d.ts#L128-L141

could be:

export class WebGLRenderer implements Renderer {
// ...
    autoClearColor: boolean = true; 
    autoClearDepth: boolean = true; 
    autoClearStencil: boolean = true; 
// ...
}

It shouldn't be an issue since types are actually exporting classes and not just declareing them and could help parsing the codebase and monitor default allocations.

Three.js version

N/A

Browser

N/A

OS

N/A

Hardware Requirements (graphics card, VR Device, ...)

N/A

[gkjohnson]

It doesn't seem this is possible unless I've done something wrong. Adding a default value onto a class member gives the following error when running tsc:

error TS1039: Initializers are not allowed in ambient contexts.

And adding one into a function signature errors with:

error TS2371: A parameter initializer is only allowed in a function or constructor implementation.

[donmccurdy]

Yeah, I don't think TS typings (as opposed to source code) allow this.

[dmnsgn]

I see. As an alternative, would you consider adding the default value as a JSDoc comment:

/**
 * @param {string} [somebody=John Doe] - Somebody's name.
 */

Or any consistent way to parse the default values across the codebase?
I am not advocating TS or JSDoc in any way, just trying to make it easier and more accessible for anyone to understand what default values. Application could be both useful in the documentation and for codebase analysis purpose.

[Mugen87]

As an alternative, would you consider adding the default value as a JSDoc comment:

It was decided in #19940 not to do this.

[dmnsgn]

Including the information in the .js file was decided against yes, but what about having the default value in the declaration files since they are manually handled? Type information is already present in the declaration so it could be simply a @default tag or anything you judge suitable for parsing.

Using my previous example:

export class WebGLRenderer implements Renderer {
// ...
        /** 
     * If autoClear is true, defines whether the renderer should clear the color buffer.
         * @default true
     */ 
    autoClearColor: boolean;
// ...
}

[Mugen87]

Well, this seems reasonable to me 👍 .

[mrdoob]

We just need someone to offer maintaining them.

@dmnsgn is that something you would like to do?

[donmccurdy]

Just to confirm here — do VSCode and other editors display JSDoc on type defs, as a fallback to JSDoc on the source itself? I'm guessing that's true because the TS compiler copies JSDoc from source TypeScript to the type definitions when it compiles TS->JS, but I'm not really sure about how editors decide what to use.

[dmnsgn]

I might be able to update the initial comment definitions and PR, then I assume if defaults are changed for some reason in the js source files, the ts declaration files should be checked in parallel with the PR or when merging.

---

@donmccurdy just tried in VSCode and it does: if I update WebGLRenderer.d.ts in node_modules/three with @default true:

        /**
     * If autoClear is true, defines whether the renderer should clear the color buffer. Default is true.
         * @default true
     */
    autoClearColor: boolean;

it will appear:

[mrdoob]

Sorry, if there is no maintainer taking care of this it will then have to be me. And I'm unable to maintain more things.

[dmnsgn]

Alright @mrdoob, I have opened the PR here: https://github.com/mrdoob/three.js/pull/20036. For maintaining it, I guess you can tag me in the future if defaults changes and these needs to be updated?