Documenting an Apps Script Library

In a previous post I discussed how to make a code library in Google Apps Script, allowing you to re-use code in various scripts.

To allow other users to benefit from your library (and you too, in time to come, when you’ve forgotten the details) you can use JSDoc in your code to ensure automatic generation of documentation for your library, and the availability of auto-completion in the editor, for those using your code.

JSDoc is a poopular standard for documenting JavaScript source code (Google Apps Script is pretty much based on JavaScript). Code published with comments delimited by /** */ produces HTML documentation for the code.

     /**
     * Repeat <tt>str</tt> several times.
     * @param {string} str The string to repeat.
     * @param {number} [times=1] How many times to repeat the string.
     * @returns {string}
     */

A JSDoc comment is a JavaScript block comment whose first character is an asterisk. This makes it look like the token /** starts such a comment, but really its just a garden-variety comment block.

JSDoc Comments are structured by starting lines with tags or other keywords that are prefixed with an @ symbol – @param and @returns are examples in the listing above.

You can also document the type of a value by putting the type name in curly braces after the appropriate tags.

Here are some variations:
Single type: @param {string} username
Choice of types: @param {string|number} userID
Arrays of one type: @param {string[]} usernames

For functions and methods, you can document parameters, return values, and exceptions these functions (or methods) might throw.

Here’s some library code from a previous post, so far without any JSDoc markup:

Click image to enlarge

Click image to enlarge

Looking at the library list, we can see that the library name is a clickable link leading to more documentation:

Click image to enlarge

Click image to enlarge

Clicking on the link, we find information on the library’s (in this case single) function, isValidFormat():

Click image to enlarge

Click image to enlarge

Unfortunately, it can’t tell us much. The two parameters taken by the function are simply listed as the generic ‘Object’, and there’s no information about what values the function may return. Let’s make a further version of the library, this sime with some JSDoc comments added.

Click image to enlarge

Click image to enlarge

Here’s the revised code:

Click image to enlarge

Click image to enlarge

Now let’s see how the documentation for our library has changed:

Click image to enlarge

Click image to enlarge

Now we can see that the function arguments required are defined as strings, and we can also see that the function will return a boolean TRUE or FALSE.

There’s an added bonus too; when the library is included in a project, the functions it contains will now show up in autocomplete in the Code Editor:

Click image to enlarge

Click image to enlarge

Here’s a list of some of the other keywords you can use:

@fileOverview provides documentation for an entire file. It’s often used with other tags @author and @version.
@class adds a description of the JavaScript class (if you code in OOP style).
@param documents information about the parameters to a function, method or class
@public documents public methods or variables.
@private documents private methods or variables.
@type documents the type of a variable or a returned value.
@returns documents the value returned by a function or method. Specify a type in curly braces {…}.
@link create an HTML link to some other documented symbol.

Some of these will refer to particular classes, methods etc. while others will apply to the whole library:

/**
* @fileOverview
* @author <a href="www.mousewhisperer.co.uk">Phil Ballard</a>
* @version 3.0
*/

/**
* @param {string} text The string to check for validity.
* @param {string} format The format to check against; name, username or email
* @returns {boolean} true or false
*/
function isValidFormat(text, format) {

JSDoc is extensive, and this is just a brief intoduction; you’ll find plenty of tutorial information online if you want to know more.