niedziela, 27 września 2020

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!

Brak komentarzy:

Prześlij komentarz

GSoD summary report

My GSoD task was to improve the Doxygen-generated documentation of ScummVM in terms of its structure, completeness, language, style, coheren...