Feature request: Types of arguments in documentation

[Itee]

Next to #12574 part 1

Currently we was have access to the variable type using hovering in the documentation. But it is maybe unusable on mobile. And is not guess to know !

The proposal is to add the type and when possible the range of the parameters.

Example:

fooParam - The fooParam of the bar class. A Floating point number, in the range 0.0 - 1.0 with default to null

instead of

fooParam - The fooParam of the bar class. Default to null

[Itee]

/ping @mrdoob So what is your opinion ?

[haroldiedema]

"Currently we was have access to the variable type using hovering in the documentation."

I've been using THREE for a few years now and find myself going to the docs for reference on a regular basis. Just to prove the usefulness of this, I've never known this "feature" was there.

While we're on the subject of documentation, I find it personally frustrating that the source code of the library itself is extremely poorly documented.

Why don't we use a JSDoc standard in the code and generate documentation based on that?

So something that looks like this:

class PointLight extends Light
{
    /**
     * Constructs a PointLight.
     *
     * @constructor
     * @param {Color|String|Number} color - (optional) hexadecimal color of the light. Default is 0xffffff (white)
     * @param {Float} intensity           - (optional) numeric value of the light's strength/intensity. Default is 1.
     * @param {Number} distance           - The distance from the light where the intensity is 0. When set to 0, then the light never stops. Default is 0.
     * @param {Number} decay              - The amount the light dims along the distance of the light. Default is 1. For physically correct lighting, set this to 2.
     */
    constructor (color, intensity, distance, decay)
    {
        // ...
    }
}

Would produce an automatically generated readable documentation. So when the code gets updated, the documentation is updated automatically as well.

I've build a similar system for a level editor for a game I'm working on, and I have to say that it works wonders:

Screenshot of the code:

• don't mind the bug in the code in this screenshot. It's an old image I had on discord :p

Screenshot of the automatically generated API reference in-editor:

[Mugen87]

Why don't we use a JSDoc standard in the code and generate documentation based on that?

This was already discussed a number of times: #2869, #4725, #11550

I think the approach of the project is clear: #3445 (comment)

[haroldiedema]

Ah my apologies, I wasn't aware.

[Mugen87]

No problem

[WestLangley]

@haroldiedema Thanks for your suggestion, anyway.

[mrdoob]

Another issue of JSDocs I've recently realised is that it doesn't scale to docs localisation (not that our docs have been localised yet anyway... 😛)

[mrdoob]

@Itee can you point me to a docs page were that change is applicable?

[Itee]

@mrdoob Almost everywhere in the doc ?!

But if you want some listing:

• timeScale: A value of 0 causes the animation to pause. Negative values cause the animation to play backwards. Default is 1. We got a 0, a 1, and negative values... So are we in a range like: -1 -> 1, -1.0 -> +1.0, or -Inf -> +Inf ?
• weight: The degree of influence of this action (in the interval [0, 1]). Values between 0 (no impact) and 1 (full impact) can be used to blend between several actions. Default is 1. This one is perfectly clear !
• PropertyMixer: ...
• far: Camera frustum far plane. Default is 2000. The valid range is between the current value of the near plane and infinity. Could i use negative values ?
• zoom Gets or sets the zoom factor of the camera. Default is 1. Zoom range is ?
• etc... etc...

Maybe this could be normalized during doc generation ?

[looeee]

far: Camera frustum far plane. Default is 2000. The valid range is between the current value of the near plane and infinity.

near: Camera frustum near plane. Default is 0.1. The valid range is greater than 0 and less than the current value of the far plane.

I don't see how this one could be much clearer.

Agreed that some of the others need work though.

Maybe this could be normalized during doc generation ?

Docs are written by hand, not generated.

Automatically generated docs tend to be pretty horrible to read.

[Itee]

@looeee

Docs are written by hand, not generated.

Ok I thought there was some helpers or templates somewhere.