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