Adopt JSDoc for documentation

[tentone]

Inline documentation

Hi, this has probably been discussed a couple of time already, i wasn't able to find recent issues regarding this).

Why not document three.js inline with code using jsdoc or similar?

That would probably help a lot to reduce documentation fragmentation and accelerate integration of new developers with already existing code? It would also help to integrate API docs in external editors (threejs editor, super powers, sublime, etc)?

I'm available to help document some of the existing code.

Thanks a lot!

Cumps

[mrdoob]

#4725 (comment)

[tentone]

I really dont like to have tons of documentation lines in the code, but since pretty much every IDE nowadays support comment folding for documentation i think its not that bad.

I believe inline documentation would be a big step forward to help removing the amount of PR being created to update documentation due to changes in the API.

[mrdoob]

I believe inline documentation would be a big step forward to help removing the amount of PR being created to update documentation due to changes in the API.

Hmm... Why is that a problem? I actually prefer it that way. Avoids additional merge conflicts.

[Mugen87]

Closing, see #12580 (comment)

[zwcloud]

So if a new user of three.js want to change the intensity of a DirectionalLight, he or she will have to:

1. open https://threejs.org/docs/index.html
2. type DirectionalLight
3. click DirectionalLight link
4. search for intensity/strength in the doc but find nothing, then possibly luckily see See the base Light class for common properties..
5. click See the base Light class for common properties link
6. search for intensity/strength, OK found it finally

Why not just support JSDoc? In a modern IDE,

var light = new THREE.DirectionalLight(0xffffff, 1);
light.i //(***)

Auto-complete happens at (***), and it shows a tooltip saying

The light's intensity, or strength.
In physically correct mode, the product of color * intensity is interpreted as luminous intensity measured in candela.
Default - 1.0.

It's apparent that which one is better. You developers are quite familiar with the API and usage, but for a new user, NO! Even for an old user of threejs, JSDoc can also bring many benefits.

Why JSDoc is important? Because it makes intellisense possible in all kinds of IDE.

IntelliSense is the general term for a number of features: List Members, Parameter Info, Quick Info, and Complete Word. These features help you to learn more about the code you are using, keep track of the parameters you are typing, and add calls to properties and methods with only a few keystrokes.

See how IDEs use JSDoc for intellisense:

• How VS2017 use JSDoc for intellisense
• How VScode use JSDoc for intellisense
• How WebStorm use JSDoc for intellisense

I would like to contribute about this.

[mrdoob]

I searched on google for "autocomplete three.js vscode" and found this:

http://shrekshao.github.io/2016/06/20/vscode-01/

Does that help?

[mrdoob]

Is there an alternative to JSDoc that doesn't need to be part of the source? Can tern be repurposed?

[looeee]

@mrdoob there's just a little bit more work involved to get that tutorial working. I posted some details on the forum a while back.

[donmccurdy]

FWIW it might be possible to write JSDoc outside of the source files, and to generate API docs, examples, and autocomplete bindings from that. For example, glTF-Validator (which is compiled from Dart) does this — https://github.com/KhronosGroup/glTF-Validator/blob/master/tool/npm_template/index.js. Could imagine having a JS file that looks like:

/**
 * GLTFLoader is a loader for glTF 2.0 assets. Lorem ipsum...
 */
var GLTFLoader;

/**
 * Parses a string or buffer to glTF asset.
 * @param {string|ArrayBuffer} asset
 * @param {function} onLoad
 */
GLTFLoader.prototype.parse = function ( asset, onLoad ) {};

/* ... */

That doesn't reduce maintenance really (maybe slightly easier to write docs this way than HTML, subjective opinion) but does make the result machine-readable.

[mrdoob]

Is there a system that...?

• Doesn't have build process
• Lives outside the source
• Supports localisation
• Can be used for VSCode autocomplete
• Can be used for search in the docs

[tentone]

Its possible to write JSDoc in separated files.

But i think that threejs should really embrace inline documentation.

It might be ugly (that it is) but its easy to maintain. Since it it attached to the code a person that changes code can immediately change documentation to match.

 * Image class is used to store image data that is used to create Textures.
 * 
 * Images can be stored in mutiple formats.
 *
 * Some formats (tga, tiff, etc) are converted to png or jpeg in order to work with the rest of the code.
 * 
 * @class Image
 * @constructor
 * @extends {Resource}
 * @module Resources
 * @param {ArrayBuffer, Base64, String} data Can be URL to image, ArrayBuffer data or base64 encoded data.
 * @param {String} encoding Image encoding, required for ArrayBuffer data.
 */

[mrdoob]

Does JSDoc support localisation?

[looeee]

I would support this if the JSDocs can stay out of the source files.

However, if we do go this path, then we really need to make the docs at threejs.org/docs be generated automatically from the JSDocs. Currently we only have one place that the docs can be out of date, with JSDoc AND online documentation then there are two places... and they will get out of sync.

[tentone]

For nunuStudio in using YUIDoc http://yui.github.io/yuidoc/syntax/index.html that can be written in separated files but does not support localization :(

[mrdoob]

Currently we only have one place that the docs can be out of date, with JSDoc AND online documentation then there are two places... and they will get out of sync.

I do not think out of sync documentation is a problem.

[looeee]

I do not think out of sync documentation is a problem.

It will certainly be confusing for users if the online documentation and the editor inline documentation don't agree.

[mrdoob]

Those things are temporary.