How to write proper documentation for Google Apps Scripts?

Question

I am a marketer who is learning to code. Currently my main weapon of choice is Google Apps Scripts. As I am diving deeper and also writing code for other people, I want to make sure that my code is well documented. Before GAS, I started with Python, where PEP-8 has a clear guideline for this. Are there any similar guidelines for GAS?

How I document functions currently (aside from having clear variable names and some inline-comments:

At the top of each script:

/**
 * @name The name of the script
 *
 * @fileoverview The overview and expected outcome 
 *
 * @author my name and e-mail address
 *
 * @version 1.0
 *
 * @changelog
 * - version 1.0
 *   - Released initial version.
 */

Below each function definition:

function buildResultsObject(contactList) {
  /**
   * Parses the contactList to create
   * an object per countryCategory ID
   *
   * The data array in the object is initialised
   * to be empty and will be filled when the 
   * data is parsed with another function.
   *
   * @param {contactList} the values from the contact list sheet as a 2-level array
   * @returns {Object} results
   *
   * Example structure of results:
   * 
   *  {'AUBAK':
   *    {
   *    'country; 'AU'
   *    'category': 'BAK'
   *    'email': 'a@b.com',
   *    'data': []
   *    }
   *  }
   *
   */

  code here
}

My questions:

• Is this how I should do it or is there a better way?
• What do the @ tags do in the comments exactly? For example I noticed that with the @name parameter, I am actually changing the name of the script that can be ran in the 'Select function' dropdown below the menu bar.

Answer 1

This following link should suffice:

https://google.github.io/styleguide/jsguide.html

Chapter 7 in the guide linked above covers all you need to know.

But you should also checkout the apps script reference documentation (and add-ons documentation) as there are some GAS specific @tags related to oauth scopes and add-ons that are only documented there.