Documentation missing imports

[LukePenkava]

Description

Is there a reason why documentation examples don't include import statements? Where am I supposed to find those? So far, as a new user of threejs, anytime I want to implement something based on documentation I have to search for it on Google how to actually import it as documentation is missing basic import information. I don't understand why official documentation is missing how to import OrbitControls for example, since clearly a lot of work has been put into documentation. This seems like strange oversight.

https://threejs.org/docs/#examples/en/controls/OrbitControls

No information, that this import is required to use any of the following features in the documentation
import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls';

Again, not realy sure how is user expected to know this, when it's not in the documentation?

Clear example of Unity documentation including all import statements at the top. Ie the documentation provides example that can be exactly copied as is and it will work.
https://docs.unity3d.com/ScriptReference/SceneManagement.SceneManager-sceneLoaded.html

For someone new to three.js, I essentially don't use your documentation, because I know it's missing things, so I have to use third party tutorials, which should not be the case, since your documentation has otherwise all the information on the class and could be all anyone really needs.

Solution

Include all import statements in your examples and make examples that can be copied as is into .js file and it will work.

Alternatives

I don't know about alternative solutions to this.

Additional context

No response

[Mugen87]

Would something like #18778 improve the situation from your point of view?

Again, not realy sure how is user expected to know this, when it's not in the documentation?

The Installation guide explains how to import three.js and its addons. Granted, there is no code example for every addon so you have to figure out the respective paths from the directory structure or the official examples (which is indeed not ideal). But even #18778 does not completely solve this issue since there is no documentation page for every addon class, see #25381.

[LukePenkava]

Would something like #18778 improve the situation from your point of view?

Again, not realy sure how is user expected to know this, when it's not in the documentation?

The Installation guide explains how to import three.js and its addons. Granted, there is no code example for every addon so you have to figure out the respective paths from the directory structure or the official examples. Even #18778 does not solve this issue since there is no documentation page for every addon class, see #25381.

Yes, something like that. In general, I think the best approach to any documentation is that the example you provide is working on it's own, when you implement it. Ie if there is required npm installation of the package, include it as first step, second part is the full content of the javascript file that will actually work when you paste it inside your js file.

This removes any confusion, problems etc. It's very clear and anyone can replicate examples in your documentation. Say I just found orbit controls as someone new in your docs, looking around for types of controls you have, then I can't replicate your example based on the information in the documentation.

[Mugen87]

Sorry, but I don't think we will add complete code examples to the documentation. We already have the official examples for this. The code snippet in the doc page will mostly show how an instance of a class is created so it's clear what is necessary for the setup. Complete code examples are listed in the Examples section. Meaning:

[Mugen87]

Regarding #18778, the PR can now be simplified since it is not necessary to distinct between node and browser anymore. We just need one import path. How to setup an import map is explained in the Installation guide.

[LukePenkava]

lol, so the decision is to not add import statements because? Or I don't understand what's the logic behind this. You do not include information how to make OrbitControls actually work. That information has to be found somewhere on Google.

The installation page ( https://threejs.org/docs/#manual/en/introduction/Installation ) is related only to installing threejs it seems. So in case of OrbitControls, your documentation page does not have an information on how to make it actually work. Just saying, I don't have major problem with it, but your docs would be better if it had that information.
I will be using third party websites to learn threejs then, I just don't understand how is the decision to not make a documentation more clear a good decision.
If there was something confusing about what I was saying, I was not asking to make full fledged examples in your docs. Just that the code you have there includes the import statement.

import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls';
 
 const renderer = new THREE.WebGLRenderer();
renderer.setSize( window.innerWidth, window.innerHeight );
document.body.appendChild( renderer.domElement );

const scene = new THREE.Scene();

const camera = new THREE.PerspectiveCamera( 45, window.innerWidth / window.innerHeight, 1, 10000 );

const controls = new OrbitControls( camera, renderer.domElement );

//controls.update() must be called after any manual changes to the camera's transform
camera.position.set( 0, 20, 100 );
controls.update();

function animate() {

	requestAnimationFrame( animate );

	// required if controls.enableDamping or controls.autoRotate are set to true
	controls.update();

	renderer.render( scene, camera );

}

[LukePenkava]

oh ok, I found the information in the installation page. You are right. If you don't want to include it there, perhaps link to the specific part of the installation page in OrbitControls page would help a lot ( would help to me ).

[Mugen87]

so the decision is to not add import statements

No no, I'm in favor of having the imports as suggested in #18778. I was just referring to more complex code examples.

[LukePenkava]

so the decision is to not add import statements

No no, I'm in favor of having the imports as suggested in #18778. I was just referring to more complex code examples.

Right, I agree with that as well.

[LukePenkava]

@Mugen87

I was just implementing fog in the scene and encountered same issue. Using all of the information on the documentation page, I was not able to figure out how to implement it. The information is not there. ( https://threejs.org/docs/#api/en/scenes/Fog )

Googled it and some tutorial had single line that told me how to do it.
"scene.fog = new THREE.Fog( 0xffffff, 0.015, 100 ); "
https://www.oreilly.com/library/view/learn-threejs/9781788833288/86ebb5c5-9fd4-4d75-aef9-e97d9aad1383.xhtml

I am realy confused about this documentation why it does not have to basic information how to implement things. Maybe I am missing something? If the docs had all the info they have and at the top was a line like this it would make it a breeze to use docs.

Sorry for complaining about this. I understand there has been a lot of work put into all of this. I am just baffled by the docs.

Edit:
This is the type of thing I would expect to be at the top of docs, so it makes it very easy and clear.

const scene = new THREE.Scene()
scene.fog = new THREE.Fog( 0xffffff, 0.015, 100 )

[mrdoob]

@LukePenkava Would you like a PR with that improvement?

https://github.com/mrdoob/three.js/edit/dev/docs/api/en/scenes/Fog.html

[LukePenkava]

@mrdoob Umm, probably yeah, why not :)

[epreston]

not completely solve this issue since there is no documentation page for every addon class, see #25381.

@Mugen87 you want that fixed up ?

[Mugen87]

Closed via #25467 and #25473.

[Mugen87]

@LukePenkava Sorry, I went ahead and updated the fog pages with code examples. Hope, it makes the pages more helpful.

[LukePenkava]

@Mugen87 No problem, if I will spot anything else, I will post it here.