Documentation

[Duiker101]

Why instead of asking someone to do it and making all this noise don't you start doing it? open source means that the community can/should contribute.

[panzerfahrer]

Guys, calm down! I don't understand what your problem seems to be. Seriously.

I didn't ask anyone to start documenting everything while I would be waiting until everything is finished. Neither does anyone wants to take away your beloved framework. I just thought I could ask if people are actually interested in more documentation (see my initial post!). I guess there is no need to discuss this in anyway. If you are comfortable without documentation, don't waste your time flaming here that you don't give a s**t about comments.

Right now there are seven votes for the ticket against the three rather negative comments here. So as for now I would say "people" do like documentation.

As for "you start doing it", since I'm currently working with andengine I definitely would contribute some documentation. But to be honest, I would feel better if there would be some people willing to do the same. Otherwise it wouldn't make much sense I guess (especially because I just started using the framework and won't use all parts of it).

So my idea would to start a clone of andengine just for the documentation. Everybody could contribute. And at some point we would ask Nicolas to merge (or do something else, like just linking to the documented version).

[AlexNunn]

Someone correct me if I'm understanding this wrong, which I probably am, but clones only see the version of the source they started with. Any further changes to AndEngine's source would not be seen by the documentation clone.

For stable features of AndEngine, this would probably be fine, but it's something to keep in mind.

[panzerfahrer]

@AlexNunn I guess the "doc clone" would need some merges then. Though, I'm not sure if this works out if the original source stays uncommented which would probably mean to merge everything every time.

[AlexNunn]

@AlexNunn I guess the "doc clone" would need some merges then. Though, I'm not sure if this works out if the original source stays uncommented which would probably mean to merge everything every time.

Yeah, I'm not very impressed with Google/Mercurial in this regard. Although, I haven't found anything better either.

I was hoping I could clone AndEngine, and use that clone to publish my customizations to AndEngine. Unfortunately, I could never figure out how to do that and still be able to merge the latest AndEngine code at the same time. Disappointing.

[Rev.Tyler]

@AlexNunn I guess the "doc clone" would need some merges then. Though, I'm not sure if this works out if the original source stays uncommented which would probably mean to merge everything every time.

Yeah, I'm not very impressed with Google/Mercurial in this regard. Although, I haven't found anything better either.

I was hoping I could clone AndEngine, and use that clone to publish my customizations to AndEngine. Unfortunately, I could never figure out how to do that and still be able to merge the latest AndEngine code at the same time. Disappointing.

What I do to keep my customizations is just go in to the repository browser before updating, hit commit which saves all of your changes (but doesn't upload them). That creates a new line in the list of updates. Right click your new line then create a patch. Now, all you have to do is revert your changes, update to the newest version and apply your patch.

It sounds like a process but after you do it once or twice it goes fast.

[AlexNunn]

I've been using Synchronize, and then Pull and Update. Appears to work, and gives me a chance to review the changes.

I was hoping for a way to publish my changes other than a patch, but oh well.

[panzerfahrer]

I just started a project clone. Well, it's not really a repo clone but rather a copy (offers more options with the google hosting) ... so I'm not quite sure if it will work out for everybody.

http://code.google.com/p/andengine-doc/
Contributors and suggestions welcome!

[jaym]

I don't see how there should be legitimate written documentation in order for people to be able to work with andengine. Everything and anything you need to know about the engine can be found in the repository. Just keep it open, go through the different files. The source code is basically documentation in itself. The classes and methods are all pretty accurate in their naming, which would be listed the same in a glossary. Click the class file you want to learn about and just start reading.

If you don't understand, maybe start here http://www.java2s.com/Tutorial/Java/CatalogJava.htm

[AlexNunn]

I don't see how there should be legitimate written documentation in order for people to be able to work with andengine. Everything and anything you need to know about the engine can be found in the repository. Just keep it open, go through the different files. The source code is basically documentation in itself. The classes and methods are all pretty accurate in their naming, which would be listed the same in a glossary. Click the class file you want to learn about and just start reading.

If you don't understand, maybe start here http://www.java2s.com/Tutorial/Java/CatalogJava.htm

I think part of the problem is that a lot of people trying to use AndEngine have little experience with Java. They're not familiar with the common practices, patterns, and letting the IDE walk them through the API.

Personally, I found AndEngine pretty easy to get working. But, I've been studying game design for several years now as a hobby, I have 10 years of experience programming web-based Java server applications, and I spent close to 8 years doing interoperability with enterprise manufacturing software where only the obsolete version was documented.

YMMV