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.