Investigate and implement a documentation system

[VitM]

While a wiki is well and good for documentation at a high level, i.e. for designers to read up on KGE implemented tools, documentation for the code would be brilliant too have.

The system that comes to mind is Doxygen (http://www.stack.nl/~dimitri/doxygen/), generating documentation from the source code. This is good because coders can document in the same place they code, tying the code implementation process with the after-implementation support/maintenance process, making the overhead for the lifetime of the code less.

However, we should look at any alternatives to see what they can offer. I do not believe anyone on the team has any previous experience with C++ documentation systems, but if they have, now is a good time to speak up.

[VitM]

Apparently the Doxygen source is available for download and compilation. From talking with John, it seems like it might be cool to use the source and compile it for our needs, although now I'm not really sure how this is going to fit into our structure.

I guess we're going to need a separate documentation project/automated build that will update and auto generate the documentation with every build. That will be using the Doxygen executable, which itself will need to be updated every now and again, either by getting the latest executable, or getting the latest source and building it.

Also something that comes to mind is that we're going to need a bit of training and exploration with Doxygen, to see what works for us, and also to see what kind of documentation we want to produce. I'd like some internal code documentation for each code file, but also a higher level piece of documentation for every modular piece of the engine, which may make sense to be a separate entity entirely.

[VitM]

I figure I just get the Doxygen windows exe, put it in a new Documentation folder in KGE and start generating some docs.

We can refactor later.

[jkeywo]

Yeah, just get it in and working, we can worry about something more complex as and when it becomes necessary.

[VitM]

I think I completely misjudged this - of course it's all project independent and whatever - what we want to put into the KGE source control is the resulting documentation, not doxygen itself! I'll start documenting some of the source tomorrow and run it through doxygen to get a feel for it, sticking it all in the Documentation folder.

[VitM]

Committed a first try of Doxygen. Was surprised to see the html output was beautiful. Only bothered documenting the Data class public interface (and only the header), and things seem to work. Slightly disappointed that the detailed description occurs at the end of the Data page, but Doxygen is nothing if not configurable.

Check out the Documentation/html/index.html file to get a taste for it.

[jkeywo]

I agree about the detailed description. Also alphabetical ordering is apparently for other people (see the class list).