Skip to content

There is no documentation or tutorial #76

Closed
ojii opened this Issue Jan 2, 2011 · 15 comments

8 participants

@ojii
ojii commented Jan 2, 2011

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

@mrdoob
Owner
mrdoob commented Jan 2, 2011

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
Owner
mrdoob commented Feb 7, 2011

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
Owner
mrdoob commented Feb 7, 2011

Eek! :D

@huttarl
huttarl commented Aug 17, 2011

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
Owner
mrdoob commented Aug 17, 2011

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

@huttarl
huttarl commented Aug 18, 2011

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
Owner
mrdoob commented Aug 18, 2011

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
dsander commented Mar 15, 2012

@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
Owner
mrdoob commented Mar 15, 2012

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
rubo77 commented Jan 22, 2013

since there is no documentation yet, this should be reopened

@mrdoob
Owner
mrdoob commented Jan 22, 2013

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.

This issue was closed.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.