GSoD 2020 b-gent

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).

Hi!

GSoD timeline is slowly coming to an end and I am slowly approaching the end of the list of high priority files defined for this project. As always, you can track my progress here:

Hi!

Week 9 has been quite productive and I’m happy with the results, even though I haven’t met my target of completing doxygen review on all high priority files.

The remaining files from the common folder are done and in PR#2627. They have been reviewed by @criezy (as always, huge thanks for the swift review) and I’m hoping we will get that merged soon.

Hi!

I’m posting a bit later than planned but I wanted to make sure one of the crucial PRs goes in before.

I’ve made some good progress this week and I am hugely thankful to @criezy for quickly jumping onto my reviews and leaving tons of great comments, some of which allowed me to understand the code better.

I just realized that I completely forgot to write a blog post for last week so this one will be short and another one is coming in a few days.

I’m struggling quite hard right now to find time for the project and constantly feel that I am behind on the timelime. Unfortunately, my availability is hugely affected by the epidemic (the situation in Poland is really bad right now). Being locked up at home with two bored, attention-craving kids doesn’t leave me much time for my regular job, let alone for GSoD.

Hi!

Just a quick update this week.

I’m still waiting for someone to have a look at PRs #2535 and #2499. Hopefully they can get it soon.

I have quite a bit of work done locally but I’m not in a hurry to open another PR. My plan is to open a PR around the weekend with 10 more high-priority files with added/edited doxygen comments. The files in question will be the ones from stream.h up to metaengine.h from this list.

I am still investing a significant chunk of my time into developing the knowledge of aspects of C++ used in ScummVM headers. Figuring out how streams work was the latest challenge 🙂

Hi!

The last week has been very busy and I’ve spent a lot of time working on finalizing PRs #2535 and #2499. The diff is quite massive so good luck to the reviewers 🙂

I am slowly crawling through the high-priority header files, as defined in the spreadsheet. Some of them can be really time-consuming, I think I spent over two days on str.h. A huge chunk of this time is spent on reading, googling, and expanding my knowledge of C++: how to understand operator functions, how iterators work, streams, arrays, lists, strings…I’m surely learning a lot but it annoys that it takes so much time that is then not really reflected in the work I’m submitting.

Hi!

I’m doing this blog post a bit late when week 5 has already started. I’ve had some busy, tough days recently due to sick family (autumn and kids generally don’t go well together) and couldn’t devote as much time as I would like for my GSoD project. I’m a bit behind on the timeline right now but not really worried as I’m sure I can catch up with everything.

Right now PR#2499 is open with some more reviewed header files from the common folder. This is something I would probably like to get merged as soon as possible.

Hi!

Work is ongoing and I am still mostly focusing on reviewing doxygen blocks in the header files of the ‘common’ folder.

In the meantime, some things have been merged:

• PR#2361 – documentation generated from the ‘common’ folder is now nicely structured and divided into groups. Grouping will ultimately be applied to all header files in the project.
• PR#2457 – everyone can now easily build the doxygen documentation using a make command or the provided .sh script (big thanks to Thierry for his help with the scripts)
• PR#2467 – doc edits in header files
• PR#2488 – doc edits in header files

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: