I know from looking at newsletter stats than when I show you lots of screenshots full of lovely eye candy, you click them in your hundreds! However, I've basically spent the past week up to my neck in the entirely unglamorous world of documentation.

If there is one thing I've learned over the years, it's that where possible, write tools to help you get stuff done. This week has been no exception. My objective was clear: I wanted to get all of the docblocks inserted into the Phaser 3 source code at 100% coverage. Every function, every class, every method, every constant, every property.

The aim was to do it in several steps. First I would add the docblocks themselves. These are the jsdoc formatted blocks that sit within the source. I wanted them to have the correct data types for every parameter and property. I also wanted all the return types to be added.

I was happy that the actual descriptions could come later. I would leave markers where the descriptions needed to be filled out, but having the actual docblocks would be a massive step in its own right. However, it is also a truly massive amount of work too.

To give you a sense of scale there are presently 1054 source files in Phaser 3 that need documenting. Some of those files (classes for instance) have hundreds of properties and methods within them. And every single piece needs covering.

It's not the sort of thing you can automate either. Sure, there are editor plugins like DocBlockr for Sublime, that will inspect your code and try its best to figure out what the arguments are. But on the whole, it struggles to infer anything beyond the basis, especially with a very function driven environment. For example, it simply cannot divine the properties of a configuration object and has no concept of any of the Phaser data types either. Plus when you're typing in hundreds of doc blocks by hand it is prone to human error. Mostly because it's such mind-numbing and repetitive work. After a few hours work your eyes start to glaze over and mistakes slip in.

Naturally, I wanted to keep mistakes to a minimum and my mind as un-numbed as possible. So I had to build a tool to help me out. Enter, Percy.

Percy Thrower

Percy is a web-based app that will scan a Phaser 3 source file and then intelligently work out how to inject docs into it. It does this because when we coded v3 we used the same structure and code syntax for all of our files. It doesn't have to analyze the code or do any AST parsing, instead it knows what to look for, and where.

It presents a long list of source files, which you can filter down by namespace, or view only those left to be documented:

Pick one and it will scan it and it'll go through the code, plucking out the functions or methods, figuring out what parameters they have. Some of these it will know based on their names, so it can pre-fill the data types. Those it can't I fill in manually, using a combination of a drop-down list of common v3 data types and a free-text area:

Once done it generates the docblock and injects it into the source. I can then save the code directly back into the v3 repo and it also keeps track of it in a local SQLite database.

There are lots of time-saving little tricks it can do. Such as knowing to use the correct glue when formatting method signatures, for example, you should use a hash # after a namespace to denote an instance method or a period for a static one. I also made the decision to make use of the @since tag so we can keep track of which version of Phaser something was added.

Most importantly of all, because the docs are being injected by code, there are no typos in the core of them. It's possible I may still type a data-type, but at least the formatting of everything will be completely consistent. And when you've got really complex configuration objects to document, like below, that's really important!

In order to retain as much of my sanity as possible while doing this work, I needed some progress charts. In short, for my own sake, I had to know how much there was left to do! As I'm logging the doc'd files to a database I now know that. Percy will happily tell me what the overall completion percentage is (as of today it's 19% - 200 files done out of 1054). And it will show me which files and sections are completed or pending.

As I mentioned at the start this is a two-step process. The first is this docblock work. Then the next stage is to go through all of the files and replace the '[description]' tags with an actual description of the property or method.

However, by completing the docblock work it means we can look at TypeScript definition generation, because for that all you need are the correct data-types in place, and we'll have those. It also means that editors that offer code completion based on JSDoc scanning, should now start to show you argument lists and the like.

Putting the actual descriptions into the source will be a large amount of work too of course. But breaking it up into steps like this makes it feel achievable. It's no longer an Everest to climb, it's now a range of smaller but more manageable peaks. I built the tools using a mixture of node scripts, plain JavaScript, a bit of jQuery (yes, yes, sue me) and Bootstrap. You can find all the tools in the phaser3-docs repo although I wouldn't even try to run them locally as they're not meant for public consumption.

The final stage is, of course, generating the actual doc files from all of this work. I've already done quite a bit of work on that and it will involve more custom tools. I'm going to be offering the full docs as a SQLite database file (as well as more traditional html format of course) which I think will be really useful for anyone wanting to build the docs into their own tools. It will also allow me to offer a really advanced documentation front-end on the Phaser web site. The ability to truly search docs, filter by data-types, expand examples in-line and directly link to related to tutorials will be great. Plus, it will open the docs up for easy translation.

Oh, and why did I name this tool Percy? It's named after Percy Thrower, who was a famous British gardener around the time of WW2. His surname means 'someone who twists fiber into yarn' - and honestly, modernizing that farming concept slightly, it feels like I'm doing that here: extracting the meaning of the code and twisting it into documentation which will tell its own story.

Phaser 3 Labs

Phaser 3 Beta 6 is out and ready for testing.

Visit the Phaser 3 Labs to view the new API structure in depth, read the FAQ, previous Developer Logs and contribution guides.

You can also join the Phaser 3 Google Group or post to the Phaser 3 Forum - we'd love to hear from you!