PBS 37 of x – JSDoc Demo

This post is part 37 of 92 in the series Programming by Stealth

In this instalment we take a break from what we’ve been doing to take an in-depth look at code documentation. I’ve regularly included documentation generated with JSDoc as one of the inputs to the challenges, and I’ve done so with the implicit assumption that those docs would be intuitively meaningful to you all. Talking with Allison two things became clear to me – firstly, that I had made this implicit assumption, and secondly, that it was completely wrong! Code documentation is a lot like man pages on the terminal – the structure of how the words are presented often carry as much meaning as the words themselves. With decades of experience this is obvious, but it’s not intuitively obvious to novices.

To remedy this I thought it would be useful to go through the entire cycle of documenting one function, and that the appropriate format for that was a screencast. When I sat down to record the screencast I couldn’t help but use the opportunity to share my toolkit with you all, so the screencast starts with a little demo of the development tools I’m currently using to develop the Cellular Automaton API we’re working on as part of this series.

Below you’ll find the screencast embedded, and, links to the various tools mentioned. Myself and Allison have also recorded a podcast for this instalment. I share my screen with Allison, and we walk through all the same steps as I do in the screencast, but with Allison stopping me and asking all the questions you probably are as you watch the screencast. When published, that podcast will be linked into this post.

Listen Along: Chit Chat Accross the Pond Episode 494
https://media.blubrry.com/nosillacast/traffic.libsyn.com/nosillacast/CCATP_2017_07_07.mp3

The Screencast

Links

GitHub – github.com (free for Open-Source-licensed code)

The GitHub Desktop Client – desktop.github.com (free)

Komodo Edit – www.activestate.com/… (free)

Dash – kapeli.com/… ($24.99)

JSDoc – usejsdoc.org (free)

NodeJS – nodejs.org (free)

The Minami JSDoc Theme – github.com/… (free)