JMonkey JavaDoc vs Wiki Documentation

I’ve been working through the beginner tutorials on the Wiki (actually, I’ve been using the SDK built-in Help files moreso) and they tutorials and Wiki/Help documentation is proving to be very good for a beginner like me to follow (Thanks for that to all involved especially @pspeed!). That being said, I’ve noticed that for many, if not most, of the API’s if I look at the JavaDoc it is fairly sparse in what it describes about the API’s. Almost all the Really Good Stuff is documented in the Wiki/Help files instead. It would be really helpful if a lot of that documentation was incorporated into the Package and/or Class JavaDoc and if more of the methods/properties had documented JavaDoc example/proto-types with explanation. I can see how rolling a lot of the Wiki/Help documentation back into the JavaDoc package and/or class JavaDoc entries in the code could be very helpful.

I would be willing to make patches to include more relevant JavaDoc, pulling information from the Wiki/Help files (including examples) as necessary if that is something the project would consider accepting. For me, it would help to solidify the concepts for myself so I wouldn’t feel like I was wasting my time, plus, it would bring more of the documentation into a way that would be more useful to use from the IDE (pop-up hints, pop-up JavaDoc with auto-complete etc).

Is this something I should pursue or is the consensus that it is better to keep this kind of documentation out of the JavaDoc and only in the Wiki/Help?

Kind Regards,

Gerry B

1 Like

Its pretty well known that the JavaDoc is lacking, so any help would be good there.

I would say though that certain things should not go into the JavaDoc, tutorials that touch many APIs probably don’t make much sense on a single class or package. On the other hand, a “mini-tutorial” that explains how to use a particular class or package would better.