Skip to content

Latest commit

 

History

History
166 lines (115 loc) · 3.5 KB

jsdoc-comments-basics.md

File metadata and controls

166 lines (115 loc) · 3.5 KB

JSDOC Comments

2022-02-21

There are three things we can do to improve our code:

  1. automated testing (best)
  2. good comments (best)
  3. typing (good)

This meeting is to address the latter 2.

VS Code works wonderfully with Typescript but that is a lot to learn. Instead we can utilize a subset of JSDOC which is supported by typescript.

elements

@fires - associate an event message @param - arguments into a function @property - parts of a typedef or public properties of a class @returns - used when a function returns something other than void @type - used when an internal variable is not obvious how it is being used @typedef - use when a variable type is used often

The typings folder is recognized by vscode as the home of type definitions. It is likely noted in a .gitignore file where it should be removed.

examples

@param

class Settings extends ChildWindow {
    /**
     * @param {BrowserWindow} parentWindow - some window
     */
    constructor(parentWindow) {
        super(parentWindow);
    }

@fires

/**
 *
 * @param {object} cfg
 * @fires broadcast
 * @returns {void}
 */
const superBroadcast = (cfg) => ipcRenderer.send('broadcast', cfg);

@property

In type definitions and often seen in a Class

@type

Typically use for in-line one-offs where the type is not obvious

/** @type {boolean} */
this.failover = settings.get('failover');

@typedef

/**
 * @typedef {object} HostType
 * @property {string} host
 * @property {number} timestamp
 * @property {Boolean} public
 * @property {number=} id
 */

 /**
 * @typedef {object} UserConfigType
 * @property {HostType[]} hosts
 * @property {string} updateHost
 * @property {boolean} failover
 * @property {boolean} allowDevTools
 * @property {boolean} allowSettings
 * @property {boolean} allowDocs
 * @property {string} versionThreshold
 * @property {string=} extension
 */

@returns

/**
 * Creates main Vue application instance
 *
 * @param {(webApp: object, hostConfig: HostType|object)} cb
 * @returns {Function} - callback
 * @fires currentHost
 */
const createApp = (cb) => {
    /** @type {HostType|object} */
    hostConfig = ipcRenderer.sendSync('currentHost', {});
    webAppConfig.url = hostConfig.url;
    webApp = new Vue(webAppConfig);
    console.log('createApp', webApp);
    return cb(webApp, hostConfig);
};

vscode config

Minimum

  1. Create a jsconfig.json file in repository root 
    {
    "compilerOptions": {
        "module": "commonjs",
        "target": "es6"
    }
}
  2. Create a typings folder in repository root.
    • include an empty .gitkeep

Resources