GSoD week 2

 Hi!

Looking at the timeline of my GSoD proect, this week was supposed to be about refreshing the doxygen skin. I worked a bit with the doxygen CSS to make the doc output more coherent with the currect ScummVM website, for example using similar colors. This didn't turn out to be a great idea and decreased the overall readability of documentation, so in the end, this change has been reverted. As agreed through a Discord poll, we are going back to a vanilla doxygen skin for now.

At the same time, I am still working on header files from the common folder. Let me explain what I mean when say I'm 'working' on them:

•  Make sure each header has a @defgroup element with (at least) a decent group decription.
•  Make sure the language is grammatically correct and coherent. I will write a blog post with a summary of the styleguide that I'm using. It's really just in my head right now and should ideally end up as part of this documentation in the future.
•  Correct doxygen errors, for example:
• Typos in doxygen commands.
• Discrepancies when describing parameters in functions (different parameter name in the doxygen block vs what is in the code).
• Fixing broken references.
• Escaping characters that create problems. For example, doxygen will try to interpret anything within sharp brackets '<>' as an HTML/XML element.
• Add @name commands to group some related structures.
• What I should be doing more - trying to figure out and add descriptions for some functions or missing parameters. This is the hardest part for a non-developer who isn't very familiar with the project yet.

Another PR with some more reviewed header files is open now.

Week 3 and 4 are officially focused on documenting the common code. I got myself a bit of a headstart but this is a massive chunk of work so keep your fingers crossed for me!

GSoD week 1

Hi!

As the first week of my GSoD project is coming to an end, I'd like to give you a recap of what I've managed to accomplish so far.

I've worked a bit with my original pull request which was part of my GSoD application. I removed some files from it to restrict the scope and right now it is purely focused on adding doxygen groups to files in the common folder. This will greatly improve the structure of the doxygen output.We are still making some decisions there regarding terminology but I'm hoping this can go in pretty soon. You can view the output of that PR here.

Another PR opened right now is for the doxygen build framework. The idea is to put the doxygen build files in the main project repository. This will make it super easy for anyone who commits code into the repository to run a doxygen build on their updated header files, in order to check if the doc output is fine. You won't even need to push the files to do this, the build just runs locally from CLI using a simple doxygen command. Ideally, this kind of check could even become part of the ScummVM CI in distant future, but right now there are too many doxygen errors to even think about it. From my point of view, this PR is not very urgent - I have my local setup which I am using when rebuilding the doc a over and over as I work on the header files. What we commit into the repository needs to properly reviewed and discussed.

As to the main part of my work - according to the timeline, the first two weeks are about setting up the doxygen build and giving it a proper look. This is ongoing in the PR mentioned above. As the discussions there happen, I have started my work on the header files from the common folder, checking the language, doxygen usage and structure, adding missing information etc. I've got the first PR opened for a couple of header files and some more changed locally which will be put in a PR very soon.

The idea right now is to crawl over all of the header files alphatebitally and opening PRs for sets of 5-10 changed files. I don't think it makes sense to wait until I have done my work on all files from the common folder and only then open a pull request. That is 80 files and I don't want a discussion on one of them to block merging of all the other ones. Also, the longer the files remain in a pull request, the higher the risk of some nasty merge conflicts.

In week 2, I will continue my work in the common folder, hopefully reaching system.h within this week. This file is more important than the other ones and will require extra thourough review, and possibly extra support from the community to make sure everything in there is described in the proper way.