### Jul

#### 8

# PBS 37 of x – JSDoc Demo

Filed Under Computers & Tech, Software Development on July 8, 2017 at 1:26 am

- PBS 1 of X – Introduction
- PBS 2 of X – Introducing HTML
- PBS 3 of X – HTML Block Elements
- PBS 4 of X – HTML In-line Elements
- PBS 5 of X – Images & Links
- PBS 6 of X – Introducing CSS
- PBS 7 of X – More CSS
- PBS 8 of X – CSS Positioning
- PBS 9 of X – More CSS Positioning
- PBS 10 of X – Yet More CSS
- PBS 11 of X – Tables
- PBS 12 of X – Introducing JavaScript
- PBS 13 of X – JS Conditionals
- PBS 14 of X – JS Loops & Arrays
- PBS 15 of X – JS Functions
- PBS 16 of X – JS Callbacks
- PBS 17 of X – JS Objects
- PBS 18 of X – JS Miscellany
- PBS 19 of X – Some JavaScript Challenges
- PBS 20 of X – JS in the Browser
- PBS 21 of X – jQuery Basics
- PBS 22 of X – jQuery Events
- PBS 23 of x – Creating Elements with jQuery
- PBS 24 of x – Creating a JavaScript API
- PBS 25 of x – A Case Study (bartificer.linkToolkit.js)
- PBS 26 of x – HTML Data Attributes with jQuery
- PBS 27 of x – JS Prototype Revision | HTML Forms
- PBS 28 of x – JS Prototype Revision | CSS Attribute Selectors & Buttons
- PBS 29 of x – JS Prototype Revision | Glyph Icons
- PBS 30 of x – Comparing JS Objects | Introducing WAI-ARIA
- PBS 31 of x – JS Static Functions | Checkboxes & Radio Buttons
- PBS 32 of x – JS Error Handling Revision | HTML Selects
- PBS 33 of x – JS Testing with QUnit
- PBS 34 of x – More JS Testing with QUnit
- PBS 35 of x – HTML Text Input | Introducing ‘Life’
- PBS 36 of x – More HTML Text Input | More Cellular Automata
- PBS 37 of x – JSDoc Demo
- PBS 38 of x – Taking Stock
- PBS 39 of x – HTML5 Form Validation
- PBS 40 of x – HTML5 Custom Validations with jQuery
- PBS 41 of x – Form Events
- PBS 42 of x – Playing the Game of Life
- PBS 43 of x – Introducing JavaScript ES6
- PBS 44 of x – ES6 Arguments & Objects
- PBS 45 of x – ES6 Arrays & Strings
- PBS 46 of x – ES6 Spread Operator, Arrow Functions & Classes
- PBS 47 of x – ES6 Polymorphism
- PBS 48 of x – A Closer Look at ‘this’ and ‘static’
- PBS 49 of x — Improving Our Cellular Automata
- PBS 50 of x — A Worked Example (Object Explorer)
- PBS 51 of x — Cellular Automata Wrap-up
- PBS 52 of X — Introducing Bootstrap 4
- PBS 53 of X — Bootstrap Utilities
- PBS 54 of X — More Bootstrap Utilities
- PBS 55 of X — Bootstrap Content
- PBS 56 of X — More Bootstrap Content
- PBS 57 of X — The Bootstrap Grid
- PBS 58 of X — Bootstrap Breakpoints
- PBS 59 of X — More Bootstrap Breakpoints
- PBS 60 of X — Bootstrap & jQuery
- PBS 61 of X — Bootstrap Jumbotrons & Badges
- PBS 62 of X — A Basic Bootstrap Form
- PBS 63 of X — Bootstrap Buttons
- PBS 64 of X — Bootstrap Form Layouts
- PBS 65 of X — Bootstrap Input Groups
- PBS 66 of X — Bootstrap Form Validation
- PBS 67 of X — Introducing Bootstrap Dropdowns
- PBS 68 of X — Bootstrap Navs
- PBS 69 of X — Bootstrap Navbars
- PBS 70 of X — Bootstrap Modals & Toasts
- PBS 71 of X — Bootstrap Spinners
- PBS 72 of X — HTML5 Templates
- PBS 73 of X — Mustache Templates
- PBS 74 of X — More Mustaches
- PBS 75 of X — AJAX Intro
- PBS 76 of X — AJAX with jQuery
- PBS 77 of X — More Callbacks & More AJAX
- PBS 78 of X — is.js & Bootstrap Popovers
- PBS 79 of X — Introducing Javascript Promises
- PBS 80 of X — JavaScript Promise Chains
- PBS 81 of X — The JavaScript Promise Utilities
- PBS 82 of X — Async & Await
- PBS 83 of X — Bootstrap Cards

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

## 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)

Great screencast. Well done !