My GSoD task was to improve the Doxygen-generated documentation of ScummVM in terms of its structure, completeness, language, style, coherence, and overall usability.
Completed tasks
This is my final GSoD deliverable:
https://doxygen.scummvm.org/modules.html
To be clear, I have not created all of this from scratch. Doxygen comments have existed in ScummVM header files since forever, as they are a standard way of documenting C and C++ code, so that it can be used and understood by other developers (which is of huge importance especially in an open-source project).
However, the existing doxygen documentation was to a large extent incomplete and random. There was practically no structure to it, which I pointed out in my initial pull request to the repo that was part of my GSoD application. You can compare the screenshot of the old structure in that PR to the currently hosted version.
The specific tasks completed during GSoD involved:
Setting up doxygen build configuration. In the course of discussions with developers, we decided to bring the doxygen build framework from a separate repository to the main one and change the configuration to a large extent.
Refreshing the style of the doxygen output. This was a low priority task. I prepared 4 different CSS alternatives, uploaded them to my github.io server and presented to developers. The most favored option was chosen by popular vote.
Adding doxygen groups to all header files from the main folders of the scummvm repository to create a structured documentation set. This was done at the same time as the actual review of the files (next point).
Thoroughly reviewing all doxygen comments in the most important header files from folders ‘common’, ‘image’, ‘engines’, ‘graphics’, and ‘audio’.
In the course of GSoD, 12 of my pull requests were merged into the repository, all of them properly reviewed by code owners. The diffs in these pull requests demonstrate what kind of additions/changes I was making in these files. A typical ‘review’ of doxygen documentation in a header file involved:
Making sure the output would appear correctly in the structure.
Making sure every single C++ element from the file had doxygen documentation.
Checking and fixing doxygen syntax, or adding doxygen elements to improve the final output.
Checking and fixing doxygen errors, such as broken references or incorrectly documented arguments.
Typical language and style check.
After opening a PR, I would always generate an HTML documentation set for the specific set of files covered in the PR and upload it to my github.io, to provide reviewers with a preview of how my changes affect the resulting output.
I was also documenting my progress by creating weekly blog posts which the organization kindly hosted on their Planet platform so that anyone interested could learn exactly what I was working on.
Prioritization
After 2-3 weeks of the project, both me and mentors realized we could approach in a more efficient manner. I started off reviewing the files alphabetically, whereas the correct way would be to approach them from the highest to lowest priority. The other reason for this was that the reviews were taking longer than expected and it became obvious that reviewing all header files in the large ScummVM codebase was unrealistic.
We decided to create a Google Spreadsheet that contained all the header files which were in scope of GSoD, and a mentor assigned a priority to all of them. We decided to focus on high priority files first and then, if possible, move to lower priorities.
All high priority files have been reviewed and a number of the lower priority files underwent a language and style review.
Current state of the project
At this point, the most essential and most frequently used header files in the project have complete and informative documentation. This means that open-source developers trying to work with ScummVM code can now rely on documentation much more than before. Whenever they are in doubt how to use a certain method or structure in their code implementation, the new doxygen documentation should help them a lot.
The documentation set is well-structured, which means it is now possible to find information by just navigating the menu on the left, rather than trying to search and hoping for the best.
All this is particularly critical when it comes to attracting new contributors to the project as it lowers the initial level of difficulty when working with the ScummVM codebase.
Follow-up work
The final deliverable is not perfect and still requires work. Firstly, only high-priority header files ended up in the scope of GSoD, plus a small number of lower priority ones. This means that there are still some blank spaces in the documentation that need to be filled. There are some files that lack doxygen almost completely, and a close cooperation of a technical writer and developers will be required to fix these cases.
Secondly, I will be creating a doxygen style guide so that developers are aware of the rules for using doxygen. Most importantly, that everything should be documented. This is essential in an open-source project where developers sometimes come and go. If they leave their piece of code undocumented, it might become a problem. I already have a full set of rules in mind but need to discuss with the main stakeholders of the project and then include it in documentation.
Another potential improvement is adding more content to the main landing page of this documentation. It is currently almost blank while it could serve as a source of useful information, like a description of the high-level structure of the codebase that would help new developers navigate the source code.
Challenges
The biggest challenge I faced was that I was essentially working on the same set of files that all other developers. My deliverable is not created from a separate set of documentation source files that nobody else was interested in apart from me. It is generated from ‘living’ code. So whenever I was changing something in a file on my fork, it was always highly probable that some developer was making changes there too, and we would end up merging at roughly the same time. This is the case especially for very active projects, like ScummVM.
As a consequence, while the review of my PR was ongoing, some merge conflicts would be appearing and some of them could be quite nasty. Because of one such conflict, I had to completely revert my review of one big file that took me several hours to complete.
Summary
Overall, I see this project as a big step towards having really valuable developer documentation in ScummVM. There are definitely some further improvements that can be made (and I will be working on them), but compared to the state of this documentation from three months ago, the progress has been considerable.
