Documentation is important to keeping a codebase understandable as it grows in size, complexity, and innovation.

JSDOC is a documentation tool to help structure your documentation.

A Simple Example

A func definition that is annotated with JSDoc...

/**
@func
split a str composed of words into an arr of words

@tags
nlp

@notes
strips away single quotes that exist at the beginning or end of a word

@param {string} words
@return {string[]} the space-split words
*/
export const splitWord = words => words.match(/[^\x00-\x2f\x3a-\x40\x5b-\x60\x7b-\x7f]+/g) || [];

A func that uses that splitWord func...

/**
@func
turns str into a URI conforming slug

@param {string} s - the str to be slugified
@return {string} the slugified str
*/
const getSlug = s => {
  return pipeStr(
    removeByRegex(/[\u0300-\u036f]/g), // removes diacritics, e.g. è -> e
    removeByRegex(/[^a-zA-Z0-9\s]/g), // only keep numbers and alphabet
    splitWord,
    joinByDash,
    getLowerCase,
  )(s);
};

Example Hover Tip

After the func's documentation is added, wherever you use the func, hit the hover tooltip shortcut and you'll get this JSDoc informative popup:

Set Shortcut Key

To activate the hover popup (called showDefinitionPreviewHover in VSC), first place your cursor on the func name, then hit the default shortcut keybinding (or you can create a custom keybinding). I have my custom binding set to cmd-n (ctrl-n)...

{
    "key": "cmd+n",
    "command": "editor.action.showDefinitionPreviewHover"
  },

What the Hover Popup informs you of

The Hover dialog will...

• show you the function source code itself
• the parameter types
• the return type
• the natural language documentation of the function, explaining what it does

How to set up JSDoc

See my prior post here...
https://dev.to/functional_js/quick-tip-setup-typescript-type-checking-with-your-pure-javascript-19ma

More coming soon

Stay tuned for more!