Why Documentation is not updated??

[czupakabra]

Like in title. Why Documentation is not updated?? one example: in documentation we have: Animation(root, name) root -- The mesh to animate. name -- The name of the animation

in code we have THREE.Animation = function ( root, data ) {

man please star update the documentation or star making more comment in code

[getzelone]

I agree... The dev do a hard work to update but dont write the documentation to explain what they did so we can't use anymore some parts. I dont know either how to anim a js model with bones and different animations.

[mrdoob]

Sorry about that... We do what we can but we definitely need help with that.

[wilson0x4d]

if i were the responsible developer i would be horribly dismayed at this post.

i would tell you that i'm sorry i spent my time improving code, but then failed to update documentation.

i would apologize, and then suggest maybe you, the community which seems to be benefiting from my contributions, could take a moment and message me asking if the API is final. and, if it is, suggest that you could also update the docs since you've already spent the time to figure it out.

of course, i'm not a threejs developer. just saying. personally I look at the core javascript, but agree it's frustrating when breaking API changes are made. this is a problem ALL developers should be more wary of, even if they ditch documentation altogether:

1. don't change call signatures such that they break
2. if you do, probably no choice, consider emitting a log line if an incorrect type is detected (perhaps at least until documentation is up to date, or some time has passed)
3. adopt DI-friendly call signatures, so if inputs need to change the signature doesn't necessarily change

[mrdoob]

What's a DI-friendly call signature?

[greyelf]

In this context I believe DI stands for Dependency Injection

[satori99]

Has there been any thought given to generating docs from code comments? Something like jsdoc? It would be much easier to ensure docs are up-to-date with the code if the method sigs are documented in the code files too.

[caseygrun]

Kind of a harsh thread... The OP has a point though; three.js is a great library and the authors clearly put tons of time into answering questions here and on StackOverflow, but this care isn't always reflected in the official docs :(

I'd like to contribute to fixing this by updating some of the docs. Is there some leading such an effort already? Here's a quick list of some of the areas that seem most in need of attention (e.g. docs totally missing), but I imagine there are plenty of others that are out of date...

Core http://threejs.org/docs/#Reference/Core/BufferAttribute http://threejs.org/docs/#Reference/Core/BufferGeometry (attributes)

Materials http://threejs.org/docs/#Reference/Materials/ShaderMaterial http://threejs.org/docs/#Reference/Materials/RawShaderMaterial

Extras/Curves (More or less everything)

Extras / Geometries http://threejs.org/docs/#Reference/Extras.Geometries/ShapeGeometry http://threejs.org/docs/#Reference/Extras.Geometries/ParametricGeometry http://threejs.org/docs/#Reference/Extras.Geometries/PolyhedronGeometry http://threejs.org/docs/#Reference/Extras.Geometries/ShapeGeometry http://threejs.org/docs/#Reference/Extras.Geometries/TubeGeometry

Extras / Helpers http://threejs.org/docs/#Reference/Extras.Helpers/DirectionalLightHelper http://threejs.org/docs/#Reference/Extras.Helpers/EdgesHelper http://threejs.org/docs/#Reference/Extras.Helpers/FaceNormalsHelper http://threejs.org/docs/#Reference/Extras.Helpers/HemisphereLightHelper http://threejs.org/docs/#Reference/Extras.Helpers/PointLightHelper http://threejs.org/docs/#Reference/Extras.Helpers/SpotLightHelper http://threejs.org/docs/#Reference/Extras.Helpers/VertexNormalsHelper http://threejs.org/docs/#Reference/Extras.Helpers/VertexTangentsHelper http://threejs.org/docs/#Reference/Extras.Helpers/WireframeHelper

Extras / Objects http://threejs.org/docs/#Reference/Extras.Objects/LensFlare http://threejs.org/docs/#Reference/Extras.Objects/MorphBlendMesh

Extras / Renderers / Plugins http://threejs.org/docs/#Reference/Extras.Renderers.Plugins/DepthPassPlugin

[WestLangley]

I'd like to contribute to fixing this by updating some of the docs. Is there some leading such an effort already?

Great! Thank you. Your contribution would be welcomed by all. There does not seem to be anyone leading this effort at this time, but @TatumCreative has an interesting suggestion in https://github.com/mrdoob/three.js/pull/5375.

[gregtatum]

I've updated some of the docs previously and would love to help make this a better experience for everyone. I've spoken a few times here locally on Three.js and WebGL. I'm currently working on #5375 but can spend some time helping out with other docs as well. I'm out this weekend, but will be available again on Monday. I would love to come up with a gameplan and start knocking things out.

[caseygrun]

Nice! Yeah, #5375 looks very cool (though orthogonal to basic completeness of the documentation).

The stuff in Extras is pretty self-explanatory by looking at the source, so that should be easy for us to patch up (but therefore it'd also be pretty easy for motivated users to figure out what's going because they can just look at the source).

I'd say that the most important/urgent stuff is related to BufferGeometry/BufferAttribute, custom attributes/uniforms, and ShaderMaterial. Basically the stuff you'd want to look up in order to work on custom shaders after reading a basic tutorial online. There are plenty of such tutorials, but it takes some digging inside src/renderers/WebGLRenderer.js to figure out how all the magic is happening. I understand that many of those features are still in some flux, but they're in the core of the library and people are using them so it seems to me they should be documented.

I'm willing to start with those next week and open a PR once there's some progress to discuss. I don't want to accidentally saddle @mrdoob , @WestLangley and co. with more SO questions by making the documentation for those confusing bits worse!

[mrdoob]

@caseygrun That would be great!

You should be edit the files directly by clicking on the "Edit page" button on the top right. That will create a PR once you save.

Feel free to ask any questions you may have here.

[mrdoob]

Oh shit, they moved the "close" issue button :P

[caseygrun]

Other open documentation issues: #5365 (Raycaster), #5187 (Euler/Quaternion), #4667 (BoundingBoxHelper), #4645 (MeshFaceMaterial), #4557 (General documentation complaint), #3716 (CSS3DRenderer)

[caseygrun]

I've started fixing BufferGeometry and BufferAttribute in #5406, which was merged this morning. I've also opened some general discussions about the docs in #5405 and #5410.

ShaderMaterial and RawShaderMaterial seem like the next logical step, so I'd be happy to start on those. I'd also be interested in doing Extras/Curves (or at least seeing that done), since my project uses those heavily, though may not have time until next week. @TatumCreative did you have anything in particular that you wanted to work on?

[gregtatum]

I can handle the geometry. Would it be helpful to close this issue and create a master issue on documentation with some checkboxes on what needs to be handled. I can do that and manage the to do list of who's doing what and what's been accomplished.

[caseygrun]

Great, sounds good!

[mrdoob]

Sounds good indeed!

[WestLangley]

Many, many thanks for providing the necessary leadership on this task.

This will be of great benefit to a lot of users.

[gregtatum]

Sweet, let's get this documentation going! I think we're ready to close #5311. I've opened up #5411 to coordinate our efforts.