Scroll To Bottom Mystery Master Build API Documentation Member

Detective

Introduction

To drive (program) in any language, whether it is C#, Java, or JavaScript, you need to have a road map. This road map is the Application Programming Interface (API). To create a puzzle module in JavaScript for the Mystery Master, you need to understand its API. This help article explains how to create the API documentation.

Code Complete

The first step is to document all JavaScript code using JSDoc tags. Most programmers hate to document their code. But if you can't/won't explain your code, how will others understand it? Though software is never perfect, at preordained intervals (usually beyond the control of the developer) one must say "This is acceptable at this point in time." This point in time is usually marked by a version number, though I prefer to give my version as the actual date.

Install Node.js

To generate the API documentation, you need to download Node.js from https://nodejs.org/en/. The website states "Node.js is a JavaScript runtime built on Chrome's V8 JavaScript engine." The version of Node.js I downloaded is Windows (x64) 10.16.3 LTS (Long Term Support). On my computer, running the downloaded file (node-v10.16.3-x64.msi) installs Node.js to the default folder C:\Program Files\nodejs. The executable node.exe is in this folder. Setup also modifies the PATH environment variable to point to Node.js and npm.

Install npm

The setup process installs npm, "the recommended package manager for Node.js". It's website is at https://www.npmjs.com. You will need npm to install JSDoc. Run the following in a command window to see what npm packages are currently installed.

npm list -g

Install JSDoc

The npm website at: https://www.npmjs.com/package/jsdoc states that JSDoc is "An API documentation generator for JavaScript." This same statement is also at https://github.com/jsdoc/jsdoc. To install JSDoc, open a command window and enter the following:

npm install -g jsdoc

The -g installs JSDoc globally on your computer. The default location for global packages is the C:\Users\YourName\AppData\Roaming\npm\node_modules\ folder. For more information on JSDoc, visit https://jsdoc.app/about-commandline.html or https://jsdoc.app/about-configuring-jsdoc.html. Note: If you ever need to uninstall this package, enter the following:

npm uninstall -g jsdoc

Build API Documentation

To help generate the documentation, you should create a config.json file in the folder where the JavaScript files are located.



To generate the documentation, open a command window, navigate to the folder, and enter the following:

jsdoc -c config.json

This generates the documentation in the out subfolder. If the output is good, the contents of this folder are moved to the help/api folder.

Conclusion

I hope you can appreciate all the work that goes into developing an application. Besides writing code, a developer must comment the code, and eventually publish documents explaining this code. Fortunately, JSDoc is able to automate some this effort.

Unfortunately, I have a few nitpicks with JSDoc. I need to use @namespace for static classes. This is because JSDoc insists on displaying new ClassName when everyone knows that a static class should not be instantiated. I also can't figure out how to override the default sort. JSDoc sorts by member name, while I would prefer to sort by the line number the member is declared.