Documentation

[KatrinaHoffert]

Start of introducing serious documentation into MegaGlest.

Doxygen is used for creating HTML files from the sources. Right now, those HTML files are of limited use because most of the code has no useable documentation. But eventually, I hope that a useful portion of the code will have this documentation, in which case Doxygen provides an easy means of structuring the docs.

As well, the use of Doxygen forces some conventions on our documentation. I'm currently using Javadoc style documentation. It's what I'm most familiar with and it is, in my opinion, more readable than the Qt style (the first sentence becomes the brief in JD style, while Qt style has to use a tag for that).

Anyway, at the time of writing this pull request, I've documented most of the upgrade_type.h file. This pull request may have further documentation added to it before it's pulled.

There shouldn't be any major issues with merging the documentation. Even if conflicts happen, they should be easy to resolve, as there's absolutely no real changes in this branch.

I also use the following, additional conventions when documenting code:

1. Simple getters and setters don't get documented (but more complicated ones may need docs)
2. Same with simple fields.
3. I don't document obvious return values. Particularly if the description of the method pretty much says what is being returned.
4. The method description is the most important part. Everything else is optional (although I try and get most parameters).
5. With delegate methods, I simply say that they're a delegate and link to the real method (as an aside, the Doxygen visibility likely needs to be set to document private members, otherwise some links won't work).
6. Readable source code is priority over Doxygen's generated output.
7. Focus is on making members and fields documented (as opposed to documenting on a line-by-line basis). This means that most documentation should be in header files. I consider this documentation the most important because it is better suited to explain why things are done in a certain way and what the high level goal is. After all, the code itself says what the line-by-line is doing.