For those of you who have not gotten a chance to use AndEngine, it’s a powerful and mature Java based 2D game engine for the Android platform. Well designed, it’s quite a pleasure to use. For the most part that is.
The biggest flaw with AndEngine is not in the engine design itself, but rather in it’s documentation. For whatever reason, the only given documentation is a set of outdated examples that don’t work with the latest build. Many users claim that since AndEngine is open source, the source code itself is sufficient documentation. Some (not all) people on the AndEngine forums exclaim that internal documentation such as Javadocs are not needed and are a waste of time because all the necessary information is right there in the source code. I say this is wrong. Why? Well, AndEngine is a SDK. The whole point of a SDK is that it gives you functionality that you can build on without the need to understand how it works internally. Sure, if you don’t have a clue as to how the thing works, perhaps it wouldn’t hurt to have a peak, or maybe if you’re writing your own engine, you should have a more in-depth look. But if you are just looking to write an application that runs on top of the AndEngine, there is no sense whatsoever in forcing the user to understand every nut and bolt. Heck, if that’s the case, I’d expect every Java programmer to understand not only the ins and outs of the JVM and javac, but also of the operating system and hardware that the JVM runs on. Besides, what if you misinterpret what a function does? You’re a lot less likely to make a mistake with your own code if you don’t have the chance to make a mistake interpreting a function through reading the source.
So, now that I’m done with this little rant, I’d also like to mention that since it is open source, I know if I really want to, I can change this. As such, I’ve joined an unofficial AndEngine documentation project, which is far from completion, though I have contributed very little to it so far: just a build system and a tiny bit of actual documentation. That said, I’m working out some kinks in hosting the Javadocs on my website. It’ll have to be ad supported but I hope some people out there will find it useful.