Code documentation

[GoogleCodeExporter]

I'm trying to use and actually extend andengine for an augmented reality 
project (and if everything works at the end I'll most likely make everything 
publicly available).

But nevertheless how great andengine seems to be, it is a pain to work with the 
code when there is no code documentation at all. I know there is the forum, 
which probably has lot's of hints (e.g. 
http://www.andengine.org/forums/tutorials/andengine-core-terminology-t316.html).
 But I guess the last thing a developer wants to do during programming is 
reading forum threads.

So, please please add some comments to classes and methods. I'd say this 
project could grow even faster (meaning people like to work with and on the 
code) with high code quality (including comments!).

Original issue reported on code.google.com by slowpoke...@gmail.com on 11 Jul 2011 at 8:42

[GoogleCodeExporter]

(cross-reference)
http://www.andengine.org/forums/tutorials/documentation-t3951.html

Original comment by slowpoke...@gmail.com on 11 Jul 2011 at 8:54

[GoogleCodeExporter]

http://code.google.com/p/andengine-doc/

Original comment by slowpoke...@gmail.com on 15 Jul 2011 at 5:37

[GoogleCodeExporter]

Agreed, I had to search the forum for what on earth a BitmapTextureAtlas is, 
then rifle through all the results

I should just have to javadoc it

Original comment by whal...@gmail.com on 26 Jul 2011 at 11:23

[GoogleCodeExporter]

Well the discussion about this issue in the forum (e.g. 
http://www.andengine.org/forums/tutorials/documentation-t3951.html) convinced 
me that there are serious problems with providing javadoc for andengine. 
Whether the forked project is the way to go is another question. It would be 
nice, however, if
 i. the wiki at http://wiki.andengine.org/AndEngine could be open to community editing or
 ii. the project wiki in google code would be open

This would at least provide a chance to build up something like a roadmap for 
beginners (and guide the way through examples and available tutorials, which 
btw are A LOT). 

Original comment by Felix.He...@gmail.com on 28 Jul 2011 at 6:56

[GoogleCodeExporter]

Well of course a separate project just for the documentation is not really the 
best solution (if this can be considered a solution at all ... "work around" is 
probably the better word).

As for ii.: I think google project hosting doesn't allow non-members to do 
anything, except from reading, creating tickets and maybe commenting (I just 
looked it up and couldn't find any option which would allow so).

For me personally a Wiki isn't the best way either. Usually this means quite 
some work for the editors (if there are any) and again beginners would need to 
search quite a lot (depending on the used Wiki system). Though, a Wiki is 
probably much better than just a forum, which has a way too chaotic structure 
to find information on. A Wiki might be perfect for explaining concepts and 
things like that. But for plain old documentation, I think Javadoc is really 
the best.

There are indeed a lot of examples ... which aren't documented either. But 
there not that much tutorials (or I just didn't find them ;-)).

Original comment by slowpoke...@gmail.com on 29 Jul 2011 at 12:19

[GoogleCodeExporter]

Guys. Just read the forum post. People are getting a bit angry!

Surely we can all agree that it would be very easy for someone who knows the 
inner workings of AndEngine to document, say, the 10 most important classes. 
Things like Texture and Sprite. 

Even if it's just a single description of the class and its philosophy, it 
would help everyone hugely, especially new users, so people on the forum aren't 
forever having to describe what a TextureRegionFactory does.

After that I would think it wouldn't be a huge undertaking to document some of 
the more obscure classes in the same way - a brief description couldn't take 
more than a minute for someone in the know

It's a cute idea wanting the project to stay undocumented because it's open 
source and old school but the fact is it's easy to do light documentation, and 
it most certainly helps people in ways the forum and tutorials can't (What's a 
BitmapTextureAtlas? What do I use now that method x is deprecated?) without 
having to rifle through forum posts.

Original comment by whal...@gmail.com on 29 Jul 2011 at 1:53

[GoogleCodeExporter]

Agreed. I didn't know of this limitation in goolge code (well it's the same in 
github). As for the requird maintenance effort for Wikis, you are probably 
right either. This would depend on the quality standards applied to any future 
documentation. However, in our development project we have started a small set 
of wiki pages explaining the concepts we used so far. We would definitely be 
willing to share this to give something back.. I mean, andengine is a really 
great project documented or not :).

I see it this way: the goal behind a wiki should be to provide an overview and 
help to understand important concepts, a forum should answer specific questions 
and the source doc should supply developers with detailed information (e.g. in 
what reference system should coordinates be, what file types can be loaded with 
some method etc.). So all of them serve different purposes. Plus there are 
tutorials around and a lot of examples providing hands-on demonstrations. The 
examples are a great source, yet will at least need some roadmap (with which 
example should I start etc.).. Something I would expect in a forum ;).

The only danger I see in a forked project is to divide the community.. That 
feeling comes naturally after reading the replies to the aforementioned forum 
post. Plus the effort to merge in the frequent codebase changes will not be an 
easy task, especially if concepts change (c.f. Texture vs. TextureAtlas stuff). 
It would be really nice to hear Nicolas' thoughts on this.. As it seems, there 
are some people willing to add more documentation to andengine.

Original comment by Felix.He...@gmail.com on 30 Jul 2011 at 12:56

[GoogleCodeExporter]

I agree that hearing from Nicolas would help. *Any* documentation helps: wiki, 
java doc, tutorial.  So whatever you have, Felix, in the way of a wiki would 
help.

Original comment by m...@rstuv.com on 30 Jul 2011 at 1:51

[GoogleCodeExporter]

+1 I have just started using AndEngine and the method documention is needed.  I 
do not like having to stop programming just to hit up the forums in hope of 
finding an example of forum post.  The methods need to be documented so 
programmers can move through it faster.  IDE's make great use of the docs.  

Original comment by james.d....@gmail.com on 1 Aug 2011 at 4:35

[GoogleCodeExporter]

+1 
I am a 15 year old developer trying to learn AndEngine. My knowledge of 
programming is very little compared to other people and a documentation would 
be very helpful.

Original comment by sumitzs...@gmail.com on 15 Oct 2011 at 3:19

[GoogleCodeExporter]

Please don't "+1" the issue, this is a tracker not a forum and you're notifying 
people without adding anything useful to the problem.

Just star an issue in order to make it relevant.

Original comment by and.dam...@gmail.com on 15 Oct 2011 at 1:45

[GoogleCodeExporter]

+1, because mby than the developer will realize that it is important.

Original comment by TommyAng...@gmail.com on 15 Oct 2011 at 2:27

[GoogleCodeExporter]

Guys, please! There is no need to spam this ticket. Don't think that this issue 
get's fixed by posting your +1's here. People just get annoyed and start to 
ignore this.

If you read through the related forum thread (see comment#1) you'll notice that 
there is an essential problem with creating a fully-fledged documentation. The 
"old people" have no interest in putting effort in something they don't really 
need. And the "new people" don't want to volunteer (for what ever reason).

Instead of spamming this ticket (or the forum), it would be of more value for 
everybody if a couple of people would just take some minutes and write some 
comments to one of the classes.

I set up an separate project just for the documentation (see comment#2). If you 
want to contribute or have any ideas related to documenting andengine, come 
over there and feel free to file tickets. If you feel the need to discuss this 
topic, please go to the forum.

Original comment by slowpoke...@gmail.com on 15 Oct 2011 at 2:56

[GoogleCodeExporter]

I migrated slowpoke's project to GitHub and am currently adding a lot of 
JavaDoc. Check it out here:
https://github.com/digitalheir/AndEngine

Original comment by maartenh...@gmail.com on 27 May 2012 at 5:32