Seriously Lacking Documentation

[Isaac Wagner]

I've been playing with Gwen all afternoon and I was able to write a
custom renderer and get everything up and running in less than an
hour. Compared to the several days it took me to wrap my head around
CEGUI, that's pretty good! I don't mind wading through source code to
make sense of things, but when there aren't even comments with
functions explaining that the arguments do... well, it just might
frighten away anyone who doesn't want to try and make sense of that.

I'm loving Gwen so much that I would love to see it catch on and would
be more than happy to help improve the documentation. What would be
the preferred way of making contributions in that area (or do you want
to hold off on writing documentation for some reason)?

[Garry Newman]

The only reason I haven't documented it more is that not that many people were using it - so it didn't seem to need it. This is probably a self fulfilling prophecy in some way though :)

The best way would be to add to the wiki I guess, can normal people do that or do I need to give you access?

http://code.google.com/p/gwen/w/list

garry

[Isaac Wagner]

I think you're right about the self-fulfilling prophecy. Without
documentation, people may not come in numbers that would make you feel
the need to write documentation. I know that at least a few people are
using it though, so I don't think you should worry.

I don't think I can edit the wiki without permission. I would be happy
to help out there if that's the way you want to do it. Another important
thing would be in-code documentation. If you wanted to take the Doxygen
route, I would also be happy to do some patches to start adding Doxygen
comments to the more ambiguous function calls and classes. Good code
documentation beats tutorials any day.

-Isaac

[Garry Newman]

I do like Doxygen - I just don't like having all the comments in the source code. I feel like it makes the code overwhelming because it seems so huge - when in reality it's like 10 function calls.

It may be the way to go though, it seems like the grown up solution.

Although personally when I'm learning something I seek out examples of what I want to achieve first - then refer to the code descriptions later on. In GWEN's case I have tried to document the things that seem difficult but actually aren't, like making your own renderer and passing inputs and events. Those already have examples. I guess I could throw a demo together showing a simple game engine with a console and dockable windows and stuff? That might help a lot of people get started?

Anyway, I've added you as a contributor to the wiki - so if you feel like documenting something in particular that you found confusing you can :)

Thanks

garry

[Isaac Wagner]

So there were two big things that I felt were important with custom
renderers that weren't mentioned in the tutorial (and that I figured out
eventually after some hair pulling):

1. Render offsets. I had no idea why my buttons and everything else were
drawing in the corner regardless of the positions that I set for them

2. LoadFont() is never called externally. It must be called from
MeasureText() by the developer who creates the custom renderer.

3. Not as important as 1 and 2, but it was slightly confusing that the
CustomRenderer tutorial claims there are pure virtual functions in
BaseRender.h, when in fact all of the functions have empty bodies
instead of the "= 0".

and I guess another major tutorial that would be helpful is input
injection

[Garry Newman]

Yeah that all makes a lot of sense. Couple of points though..

With LoadFont - I can see the confusion. I wonder whether it would be better to have a function on the base renderer which automatically calls LoadFont and then MeasureText/RenderText. Then MeasureText/RenderText would be made protected? That would probably kill that confusion?

With point 3 - that WAS the case but I changed them quite recently so when making your renderer you could do it bit by bit instead of doing every function..

If you want to do anything then go right ahead - you don't particularly need any permission from me but I'm here if you need some questions answered.

garry