PBS 37 of x – JSDoc Demo

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 have as you watch the screencast. When published, that podcast will be linked into this post.

Matching Podcast Episode 494

Listen Along: Chit Chat Across the Pond Episode 494

You can also Download the 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)

• ← PBS 36 — More HTML Text Input | More Cellular Automata
• Index
• PBS 38 — Taking Stock →