There is no documentation or tutorial

[ojii]

For this library to be actually useful, a decent documentation is needed.

[mrdoob]

Indeed, there is no documentation. In the meantime feel free to read the code in the examples, that should give you some idea of how the library works. If you have any specific question feel free to create an issue for that.

I've seen a few games and projects using this library. So I guess whether it's useful or not it's up to the individual.

[staunsholm]

running jsdoc on THREE.js gives you quite good information:

http://www.staunsholm.dk/THREE/jsdoc/

Regards,
Mikkel Staunsholm

[mrdoob]

Interesting... Maybe at some point we could do a python script to generate such thing. Is jsdoc a single file?

[staunsholm]

read more about jsdoc at: http://jsdoc.sourceforge.net/

but no, jsdoc is not a single file. It is a perl script, with some templates and settings files along side it.

[mrdoob]

Eek! :D

[huttarl]

Good grief, this issue was closed?

I have to agree with ojii to a large extent...
Sure you can get a fair distance with Three.js even without documentation, especially if you are the developer, or if you spend a lot of time reading the code.

But suppose you want to know what kinds of objects can be passed as an argument to Scene.addObject()... Mikkel's generated docs won't tell you. How do I add hierarchical objects to a scene? I can't tell without reading the code and making inferences. If Three.js was intended to be "with a very low level of complexity — in other words, for dummies", then requiring users to dig through the code would indicate that this goal has not been reached.

[mrdoob]

Indeed. The goal hasn't been reached... yet. It's still work in progress. API is still being defined.

[huttarl]

Fair enough... but the fact that the issue was closed sends the message that there is no intent to ever write documentation. Am I misinterpreting?

[mrdoob]

Well, there are tutorials, and there are some basic documentation. The OP was saying that the library couldn't be useful without all that and I've seen some people doing stuff with the library so I would say the issue isn't valid anymore. I don't know if it was me that closed the issue or maybe the OP.

Having said that, there are intentions of writing documentation, but first we need to define an API we think it's right. We're getting there.

[elamperti]

Even though there's people who already made amazing stuff, it's really necesary to have an official documentation. I've seen many different tutorials and there are substantial differences between them.
Once the API is settled, it would be really appreciated and it will ease things for newbies (remember when you were there!). Keep up the good work :)

[dsander]

@mrdoob I did not want to open a new issue about this. I was just wondering why you decided not to use comment-driven documentation. There are a few decent tools to generate documentation based on the source code.
http://developer.yahoo.com/yui/yuidoc/#start and https://github.com/visionmedia/dox seem pretty good, with YUI Doc having the upper hand.
I think comment-driven documentation has mayor advantages over separated docs, you can write the docs while writing/updating code, new users can dig into the code while reading docs at the same time, and the documentation is always up to date when moving/deleting methods or classes.

Well anyway, I would really like to help documenting while digging through the code to learn how to use three.js. Are there some classes which will most likely change soon and therefore not worth documenting?

[mrdoob]

I just prefer keeping the code simple and clean. The current approach allows many things that compiled based methods don't make too easy.

Some classes will likely change, but I don't know which ones at this point. Better to document the current state and afterwards it would be mainly moving stuff aroun.

[rubo77]

since there is no documentation yet, this should be reopened

[mrdoob]

There is documentation:
http://mrdoob.github.com/three.js/docs/

Incomplete? Yes. Help us!

[jdonaldson]

One other reason to include jsdoc documentation is that it enables optimizations by closure compiler. It also enables better extern support for statically typed languages that compile to js.

On the topic of clutter, certain IDE's have the ability to collapse javadoc-style comments for classes and methods.