Open GoogleCodeExporter opened 9 years ago
(cross-reference)
http://www.andengine.org/forums/tutorials/documentation-t3951.html
Original comment by slowpoke...@gmail.com
on 11 Jul 2011 at 8:54
http://code.google.com/p/andengine-doc/
Original comment by slowpoke...@gmail.com
on 15 Jul 2011 at 5:37
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
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
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
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
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
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
+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
+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
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
Original issue reported on code.google.com by
slowpoke...@gmail.com
on 11 Jul 2011 at 8:42