docs: update jsdocs

Address review comments from jfmengels#301.

.eslintrc.js

@@ -14,6 +14,7 @@ module.exports = {
     'plugin:@eslint-community/eslint-comments/recommended',
     'plugin:promise/recommended',
     'plugin:unicorn/recommended',
+    'plugin:jsdoc/recommended-typescript-flavor',
     'plugin:@typescript-eslint/recommended-type-checked',
     'plugin:@typescript-eslint/stylistic-type-checked',
     'prettier'
@@ -24,6 +25,7 @@ module.exports = {
     'security',
     'promise',
     'unicorn',
+    'jsdoc',
     '@typescript-eslint'
   ],
   parser: '@typescript-eslint/parser',
@@ -128,7 +130,9 @@ module.exports = {
     'no-unused-expressions': 'off', // This rule is replaced with the TSESlint version.
     '@typescript-eslint/no-unused-expressions': 'error', // Support TS stuff.
     '@typescript-eslint/no-throw-literal': 'error', // Recommended in v8 (w/rename to `only-throw-error`)
-    '@typescript-eslint/prefer-namespace-keyword': 'error', // Recommended in v8
+    '@typescript-eslint/prefer-find': 'error', // Recommended in v8
+    '@typescript-eslint/prefer-includes': 'error', // Recommended in v8
+    '@typescript-eslint/prefer-regexp-exec': 'error', // Recommended in v8
 
     // Unsafe
     '@typescript-eslint/no-unsafe-assignment': 'off', // Blocked on typescript-eslint/typescript-eslint#1682.
@@ -151,7 +155,16 @@ module.exports = {
 
     // TODO(@lishaduck): Enable rules that require newer versions of Node.js when we bump the minimum version.
     'unicorn/prefer-string-replace-all': 'off', // TODO(@lishaduck) [engine:node@>=15]: Enable this rule.
-    'unicorn/prefer-at': 'off' // TODO(@lishaduck) [engine:node@>=16.6]: Enable this rule.
+    'unicorn/prefer-at': 'off', // TODO(@lishaduck) [engine:node@>=16.6]: Enable this rule.
+
+    'jsdoc/require-description': 'off',
+    'jsdoc/require-param-description': 'off',
+    'jsdoc/require-returns-description': 'off',
+    'jsdoc/require-returns': [
+      'error',
+      {forceRequireReturn: true, forceReturnsWithAsync: true, enableFixer: true}
+    ],
+    'jsdoc/tag-lines': ['warn', 'any', {startLines: 1}]
   },
   overrides: [
     {

lib/anonymize.js

@@ -1,5 +1,5 @@
 /**
- * This module aims to make the paths and versions used in the CLI generic
+ * @file This module aims to make the paths and versions used in the CLI generic,
  * so that the CLI tests (in the `test/` folder) have the same output on different
  * machines, and also the same output when only the CLI version changes.
  */

lib/app-wrapper.js

@@ -81,6 +81,7 @@ function initWithWorker(elmModulePath, flags) {
 
 /**
  * @param {string | symbol} port
+ * @returns {Listened<unknown>}
  */
 function send(port) {
   return (/** @type {unknown} */ data) => {
@@ -137,6 +138,7 @@ function initializeListeners() {
 /**
  * @param {string} elmModulePath
  * @param {Flags} flags
+ * @returns {ReviewApp}
  */
 function initWithoutWorker(elmModulePath, flags) {
   const elmModule = loadCompiledElmApp(elmModulePath);
@@ -146,6 +148,9 @@ function initWithoutWorker(elmModulePath, flags) {
   return app;
 }
 
+/**
+ * @returns {void}
+ */
 function stop() {
   if (worker) {
     worker.terminate();

lib/autofix.js

@@ -27,6 +27,7 @@ const StyledMessage = require('./styled-message');
  * @param {Options} options
  * @param {ReviewApp} app
  * @param {VersionString} elmVersion
+ * @returns {void}
  */
 function subscribe(options, app, elmVersion) {
   AppState.subscribe(

lib/build.js

@@ -1,10 +1,11 @@
 /**
+ * @import {CompileOptions, Sources} from '../vendor/types/node-elm-compiler';
  * @import {AppHash, BuildResult} from './types/build';
  * @import {ApplicationElmJson, ElmJson} from './types/content';
- * @import {VersionString} from './types/version';
+ * @import {ErrorMessageInfo} from './types/error-message';
  * @import {Options, Template} from './types/options';
  * @import {Path} from './types/path';
- * @import {CompileOptions, Sources} from '../vendor/types/node-elm-compiler';
+ * @import {VersionString} from './types/version';
  */
 const path = require('node:path');
 const crypto = require('node:crypto');
@@ -334,6 +335,7 @@ async function createTemplateProject(
  * @param {Options} options
  * @param {string} userSrc
  * @param {ApplicationElmJson} elmJson
+ * @returns {ApplicationElmJson}
  */
 function updateSourceDirectories(options, userSrc, elmJson) {
   let sourceDirectories = [
@@ -359,10 +361,10 @@ function updateSourceDirectories(options, userSrc, elmJson) {
 
 /**
  * @param {Options} options
- * @param {string} dest
- * @param {string} elmModulePath
+ * @param {Path} dest
+ * @param {Path} elmModulePath
  * @param {Sources} compileTargets
- * @param {string} elmBinary
+ * @param {Path} elmBinary
  * @param {boolean} isReviewApp
  * @returns {Promise<string | null>}
  */
@@ -455,6 +457,7 @@ async function compileElmProject(
 /**
  * @param {Options} options
  * @param {string} stderr
+ * @returns {ErrorMessageInfo}
  */
 function compilationError(options, stderr) {
   if (stderr.includes('DEBUG REMNANTS')) {
@@ -496,6 +499,7 @@ function compilationError(options, stderr) {
  * @param {Options} options
  * @param {Path} reviewElmJsonPath
  * @param {ElmJson} reviewElmJson
+ * @returns {void}
  */
 function validateElmReviewVersion(options, reviewElmJsonPath, reviewElmJson) {
   if (options.localElmReviewSrc) {

lib/debug.js

@@ -4,6 +4,7 @@ const options = AppState.getOptions();
 
 /**
  * @param {string} message
+ * @returns {void}
  */
 function log(message) {
   if (options.debug) {

lib/elm-files.js

@@ -1,5 +1,5 @@
 /**
- * @import {ElmFile, Source, Readme, ElmJson, ElmJsonData, SourceDirectories, Ast} from './types/content';
+ * @import {Ast, ElmFile, ElmJson, ProjectFiles, Readme, Source, SourceDirectories} from './types/content';
  * @import {ReviewOptions} from './types/options';
  * @import {Path} from './types/path';
  */
@@ -19,14 +19,6 @@ const AppState = require('./state');
 
 const defaultGlob = '**/*.elm$';
 
-/**
- * @typedef {object} ProjectFiles
- * @property {ElmJsonData} elmJsonData
- * @property {Readme | null} readme
- * @property {ElmFile[]} elmFiles
- * @property {Path[]} sourceDirectories
- */
-
 /**
  * Get all files from the project.
  *

lib/error-message.js

@@ -97,7 +97,7 @@ function stacktrace(debug, error) {
  * @param {boolean} debug
  * @param {CustomError} error
  * @param {Path} [defaultPath]
- * @returns {unknown}
+ * @returns {{type: string; title: string; path: string | undefined; message: string[]; stack: string | undefined}}
  */
 function formatJson(debug, error, defaultPath) {
   return {

lib/fs-wrapper.js

@@ -9,7 +9,7 @@ const fsp = fs.promises;
  * Read a JSON file.
  *
  * @param {Path} file
- * @param {Reviver | undefined} [reviver=undefined]
+ * @param {Reviver} [reviver]
  * @returns {Promise<unknown>}
  */
 async function readJsonFile(file, reviver) {
@@ -19,10 +19,9 @@ async function readJsonFile(file, reviver) {
 }
 
 /**
- *
  * @param {string} data
  * @param {Path} file
- * @param {Reviver | undefined} reviver
+ * @param {Reviver} [reviver]
  * @returns {unknown}
  */
 function parseJsonFromFile(data, file, reviver) {
@@ -46,8 +45,8 @@ function readJsonFileSync(file) {
 /**
  * Read a file using Promises.
  *
- * @param {string} file
- * @param {fs.BaseEncodingOptions & { flag?: fs.OpenMode | undefined }} [options={encoding: 'utf8'}]
+ * @param {Path} file
+ * @param {fs.BaseEncodingOptions & { flag?: fs.OpenMode | undefined }} [options]
  * @returns {Promise<string>}
  */
 async function readFile(file, options) {
@@ -58,10 +57,10 @@ async function readFile(file, options) {
 /**
  * Write a JSON file.
  *
- * @param {string} file
+ * @param {Path} file
  * @param {unknown} content
- * @param {string | number | undefined} [space=undefined]
- * @param {Replacer | undefined} [replacer=undefined]
+ * @param {string | number | undefined} [space]
+ * @param {Replacer} [replacer]
  * @returns {Promise<void>}
  */
 async function writeJson(file, content, space, replacer) {
@@ -85,7 +84,8 @@ function mkdirpSync(dir) {
 }
 
 /**
- * @param {fs.PathLike} file
+ * @param {Path} file
+ * @returns {Promise<void>}
  */
 async function remove(file) {
   await fsp.rm(

lib/help.js

@@ -56,6 +56,9 @@ ${Flags.buildFlags('fix', null)}
   );
 }
 
+/**
+ * @returns {void}
+ */
 function suppress() {
   const orange = chalk.keyword('orange');
 
@@ -97,6 +100,9 @@ ${Flags.buildFlags('suppress', 'suppress')}
   );
 }
 
+/**
+ * @returns {void}
+ */
 function init() {
   console.log(
     // prettier-ignore
@@ -117,6 +123,9 @@ ${Flags.buildFlags('init', 'init')}
   );
 }
 
+/**
+ * @returns {void}
+ */
 function newPackage() {
   console.log(
     // prettier-ignore
@@ -138,6 +147,9 @@ ${Flags.buildFlags('new-package', 'new-package')}
   );
 }
 
+/**
+ * @returns {void}
+ */
 function newRule() {
   console.log(`The new-rule command adds an empty rule to your review configuration or
 review package.
@@ -161,6 +173,9 @@ ${Flags.buildFlags('new-rule', 'new-rule')}
 `);
 }
 
+/**
+ * @returns {void}
+ */
 function prepareOffline() {
   console.log(`The prepare-offline command allows the tool to run in offline mode using
 the ${chalk.cyan('--offline')} flag.

lib/init.js

@@ -52,6 +52,7 @@ async function promptAndCreate(options) {
  * @param {Options} options
  * @param {Template} template
  * @param {string} directory
+ * @returns {Promise<void>}
  */
 async function createFromTemplate(options, template, directory) {
   const configDirectory = path.join(directory, 'src');
@@ -91,6 +92,7 @@ async function createFromTemplate(options, template, directory) {
 /**
  * @param {Options} options
  * @param {Path} directory
+ * @returns {void}
  */
 function logInit(options, directory) {
   const message = options.template
@@ -118,6 +120,7 @@ ${options.template ? templateRecommendation : ''}`
 /**
  * @param {Options} options
  * @param {Path} directory
+ * @returns {string}
  */
 function regularInitMessage(options, directory) {
   return `You can now define your review configuration by editing ${chalk.green(
@@ -130,6 +133,7 @@ const orange = chalk.keyword('orange');
 /**
  * @param {Options} options
  * @param {Path} directory
+ * @returns {string}
  */
 function templateInitMessage(options, directory) {
   return `You chose to use someone's review configuration which can be great to get started
@@ -155,6 +159,7 @@ I recommend you use a mix of the following approaches:
  * @param {Options} options
  * @param {Path} directory
  * @param {string} template
+ * @returns {Promise<void>}
  */
 async function create(options, directory, template) {
   const configDirectory = path.join(directory, 'src');
@@ -170,6 +175,7 @@ async function create(options, directory, template) {
 /**
  * @param {Options} options
  * @param {Path} directory
+ * @returns {Promise<void>}
  */
 async function createElmJson(options, directory) {
   const elmBinary = await getElmBinary(options);
@@ -188,6 +194,7 @@ async function createElmJson(options, directory) {
 /**
  * @param {Path} directory
  * @param {string} template
+ * @returns {void}
  */
 function createReviewConfig(directory, template) {
   fsExtra.copyFileSync(

lib/main.js

@@ -67,6 +67,9 @@ function errorHandler(err) {
   exit(1);
 }
 
+/**
+ * @returns {Promise<void>}
+ */
 async function runElmReview() {
   const {elmModulePath, reviewElmJson, appHash} = await Builder.build(options);
 
@@ -142,6 +145,9 @@ async function runElmReviewInWatchMode() {
   }
 }
 
+/**
+ * @returns {Promise<void>}
+ */
 async function prepareOffline() {
   const elmBinary = await ElmBinary.getElmBinary(options);
   ElmBinary.downloadDependenciesOfElmJson(

lib/min-version.js

@@ -50,7 +50,7 @@ function updateToAtLeastMinimalVersion(version) {
  * @param {Options} options
  * @param {Path} elmJsonPath - path to an elm.json file
  * @param {VersionString} version - version string, e.g. "1.0"
- * @returns void
+ * @returns {void}
  */
 function validate(options, elmJsonPath, version) {
   const [major, minor] = version.split('.');

lib/module-cache.js

@@ -11,6 +11,7 @@ const Cache = require('./cache');
 /**
  * @param {Options} options
  * @param {ReviewApp} app
+ * @returns {void}
  */
 function subscribe(options, app) {
   AppState.subscribe(app.ports.cacheFile, async ({source, ast}) =>
@@ -25,6 +26,7 @@ function subscribe(options, app) {
  * @param {Options} options
  * @param {string} fileHash
  * @param {Ast} ast
+ * @returns {Promise<void>}
  */
 async function cacheFile(options, fileHash, ast) {
   await Cache.cacheJsonFile(