Documentation clarity

Speaking as someone just looking at the project, I appreciate all the effort that has gone into JME so far, but it is also far slower for me to build an application with than it should be if the documentation was adequately clear/precise.  (I should be able to tell by looking at the javadocs what the expected range of values for input and output of a specific function is, etc)  I'm glad there are examples and tests, but I feel I really shouldn't have to go digging through someone else's source code to figure out how to use a particular function.

That said, I would be happy to help on this regard in the future as I become more familiar with the project/conventions.  (Though I'd hope that someone more familiar/knowledgeable than myself would start on it a little bit before that point…)

This would not only benefit new users, but also the project in the long run - as the user base grows (which would happen more quickly if the documentation was easily understandable) so will the contributions to the project.

This thread I just posted would be a perfect example, if you do not understand what I am talking about:

It is quite possible I am misusing the function, and it isn't even meant to do what I am trying to do with it.  But, if that were the case then the intent for use should be clearly stated, as "setDirection sets the direction the camera is facing." would lead me to think I can use it to make the camera face any direction I wish.  If it does indeed allow facing any direction then the min/max ranges should be given, possibly with a terse example of use - as you would see in Sun's documentation

The issue is that it is difficult to make documentation fit for everyone. Sun's documentation is very precise and detailed because it is a professional company making a product for a wide audience.

For somebody with 3D experience it will be outright obvious what the function setDirection does, what it's input values are and how to use it in general, for somebody who never worked with vectors and 3D it will be impossible to understand without very detailed documentation.

It is a common issue for open source projects to have little to no documentation, this is one consequence of the library being free.

I suggest that you get acquainted with 3D concepts, vectors and some basic physics to help you with your issue.

Take a look at some other game engines with better documentation, nearly all game engines follow the same principles so you should feel right at home when you get back to jME, also don't forget that you can always check the jME source to see what each and every method does.

I also had trouble understanding jME when I started using it, but following some of the tips I mentioned above helped me tremendously.

It's great that you want to help out with documentation, unfair. It can always be improved.

But the particular comment you pointed out, cannot be improved by min/max values. They would not make any sense. You can specify any direction (+ see response to other post). But a direction should generally be unit length (normalized).

Momoko_Fan said:

The issue is that it is difficult to make documentation fit for everyone. Sun's documentation is very precise and detailed because it is a professional company making a product for a wide audience.

I guess I would argue that it doesn't hurt to make it as explicit as possible, thus understandable to the widest audience possible - unless you think that such an endeavor would make it look bad/unprofessional.  I don't mind filling in small tidbits as I learn, as long as no one else has a problem with it. 

Here's an example of something that isn't entirely necessary, but that I would probably add:
The SimpleCanvasImpl doc page references a field tpf, which it took me a minute or two (maybe I'm just slow) to realize means TimePerFrame - and I only realized that because I noticed there was a function getTimePerFrame().  In that sort of situation I would probably add a note mentioning that it means TimePerFrame - merely because that minute or two I was wondering about it are a minute or two of my life I'll never get back, so spending a few seconds potentially saves a lot more people time down the road.

Like I said though, totally up to you guys whether you think it would be beneficial or not.

Thanks for the tips, I'm learning - it's just slower going than I expected it to be.  (It's taken me a couple days worth of reading/experimenting to properly embed a canvas in swing, display a heightmap from an image, and add controls to move the camera around the heightmap) 

P.S.  that StandardGame.getCanvas() threw me for a loop - I never did get it working properly because odd way it needs to be initialized when you set it to DISPLAY_CANVAS.  Someone might want to take a look at that, because from what I read on this forum it seems like it isn't quite implemented properly.

See and