Update ESLint config to v9 (JSDoc linting) (#591)

Our ESLint rules have been updated to v9, which includes new rules to
enforce our JSDoc conventions.

Most of the changes in this PR were a result of running
`yarn lint:fix`. There were a handful of manual changes that seemed
obvious and simple to make.

There should be no functional changes in this PR. All changes are to
comments (aside from the config update and related config changes).

package.json

@@ -70,10 +70,10 @@
   "devDependencies": {
     "@lavamoat/allow-scripts": "^1.0.6",
     "@metamask/auto-changelog": "^2.5.0",
-    "@metamask/eslint-config": "^8.0.0",
-    "@metamask/eslint-config-jest": "^8.0.0",
-    "@metamask/eslint-config-nodejs": "^8.0.0",
-    "@metamask/eslint-config-typescript": "^8.0.0",
+    "@metamask/eslint-config": "^9.0.0",
+    "@metamask/eslint-config-jest": "^9.0.0",
+    "@metamask/eslint-config-nodejs": "^9.0.0",
+    "@metamask/eslint-config-typescript": "^9.0.1",
     "@types/jest": "^26.0.22",
     "@types/node": "^14.14.31",
     "@types/punycode": "^2.1.0",
@@ -86,6 +86,7 @@
     "eslint-import-resolver-typescript": "^2.4.0",
     "eslint-plugin-import": "^2.22.1",
     "eslint-plugin-jest": "^24.1.5",
+    "eslint-plugin-jsdoc": "^36.1.0",
     "eslint-plugin-node": "^11.1.0",
     "eslint-plugin-prettier": "^3.3.1",
     "ethjs-provider-http": "^0.1.6",

src/BaseController.ts

@@ -7,7 +7,6 @@ export type Listener<T> = (state: T) => void;
  * @type BaseConfig
  *
  * Base controller configuration
- *
  * @property disabled - Determines if this controller is enabled
  */
 export interface BaseConfig {
@@ -18,7 +17,6 @@ export interface BaseConfig {
  * @type BaseState
  *
  * Base state representation
- *
  * @property name - Unique name for this controller
  */
 export interface BaseState {
@@ -63,8 +61,8 @@ export class BaseController<C extends BaseConfig, S extends BaseState> {
    * Creates a BaseController instance. Both initial state and initial
    * configuration options are merged with defaults upon initialization.
    *
-   * @param config - Initial options used to configure this controller
-   * @param state - Initial state to set on this controller
+   * @param config - Initial options used to configure this controller.
+   * @param state - Initial state to set on this controller.
    */
   constructor(config: Partial<C> = {} as C, state: Partial<S> = {} as S) {
     // Use assign since generics can't be spread: https://git.io/vpRhY
@@ -77,7 +75,7 @@ export class BaseController<C extends BaseConfig, S extends BaseState> {
    * variable on this instance and triggers any defined setters. This
    * also sets initial state and triggers any listeners.
    *
-   * @returns - This controller instance
+   * @returns This controller instance.
    */
   protected initialize() {
     this.internalState = this.defaultState;
@@ -88,29 +86,29 @@ export class BaseController<C extends BaseConfig, S extends BaseState> {
   }
 
   /**
-   * Retrieves current controller configuration options
+   * Retrieves current controller configuration options.
    *
-   * @returns - Current configuration
+   * @returns The current configuration.
    */
   get config() {
     return this.internalConfig;
   }
 
   /**
-   * Retrieves current controller state
+   * Retrieves current controller state.
    *
-   * @returns - Current state
+   * @returns The current state.
    */
   get state() {
     return this.internalState;
   }
 
   /**
-   * Updates controller configuration
+   * Updates controller configuration.
    *
-   * @param config - New configuration options
-   * @param overwrite - Overwrite config instead of merging
-   * @param fullUpdate - Boolean that defines if the update is partial or not
+   * @param config - New configuration options.
+   * @param overwrite - Overwrite config instead of merging.
+   * @param fullUpdate - Boolean that defines if the update is partial or not.
    */
   configure(config: Partial<C>, overwrite = false, fullUpdate = true) {
     if (fullUpdate) {
@@ -135,7 +133,7 @@ export class BaseController<C extends BaseConfig, S extends BaseState> {
   }
 
   /**
-   * Notifies all subscribed listeners of current state
+   * Notifies all subscribed listeners of current state.
    */
   notify() {
     if (this.disabled) {
@@ -148,19 +146,19 @@ export class BaseController<C extends BaseConfig, S extends BaseState> {
   }
 
   /**
-   * Adds new listener to be notified of state changes
+   * Adds new listener to be notified of state changes.
    *
-   * @param listener - Callback triggered when state changes
+   * @param listener - The callback triggered when state changes.
    */
   subscribe(listener: Listener<S>) {
     this.internalListeners.push(listener);
   }
 
   /**
-   * Removes existing listener from receiving state changes
+   * Removes existing listener from receiving state changes.
    *
-   * @param listener - Callback to remove
-   * @returns - True if a listener is found and unsubscribed
+   * @param listener - The callback to remove.
+   * @returns `true` if a listener is found and unsubscribed.
    */
   unsubscribe(listener: Listener<S>) {
     const index = this.internalListeners.findIndex((cb) => listener === cb);
@@ -169,10 +167,10 @@ export class BaseController<C extends BaseConfig, S extends BaseState> {
   }
 
   /**
-   * Updates controller state
+   * Updates controller state.
    *
-   * @param state - New state
-   * @param overwrite - Overwrite state instead of merging
+   * @param state - The new state.
+   * @param overwrite - Overwrite state instead of merging.
    */
   update(state: Partial<S>, overwrite = false) {
     this.internalState = overwrite

src/BaseControllerV2.test.ts

@@ -41,6 +41,12 @@ type CountMessenger = RestrictedControllerMessenger<
   never
 >;
 
+/**
+ * Constructs a restricted controller messenger for the Count controller.
+ *
+ * @param controllerMessenger - The controller messenger.
+ * @returns A restricted controller messenger for the Count controller.
+ */
 function getCountMessenger(
   controllerMessenger?: ControllerMessenger<
     CountControllerAction,

src/BaseControllerV2.ts

@@ -18,9 +18,9 @@ enablePatches();
  * the new state along with a set of patches describing the changes since the
  * last update.
  *
- * @param state - The new controller state
+ * @param state - The new controller state.
  * @param patches - A list of patches describing any changes (see here for more
- *   information: https://immerjs.github.io/immer/docs/patches)
+ * information: https://immerjs.github.io/immer/docs/patches)
  */
 export type Listener<T> = (state: T, patches: Patch[]) => void;
 
@@ -30,8 +30,8 @@ export type Listener<T> = (state: T, patches: Patch[]) => void;
  * This function will accept one piece of the controller state (one property),
  * and will return some derivation of that state.
  *
- * @param value - A piece of controller state
- * @returns Something derived from controller state
+ * @param value - A piece of controller state.
+ * @returns Something derived from controller state.
  */
 export type StateDeriver<T extends Json> = (value: T) => Json;
 
@@ -49,12 +49,12 @@ export type StateMetadata<T extends Record<string, Json>> = {
  * Metadata for a single state property
  *
  * @property persist - Indicates whether this property should be persisted
- *   (`true` for persistent, `false` for transient), or is set to a function
- *   that derives the persistent state from the state.
+ * (`true` for persistent, `false` for transient), or is set to a function
+ * that derives the persistent state from the state.
  * @property anonymous - Indicates whether this property is already anonymous,
- *   (`true` for anonymous, `false` if it has potential to be personally
- *   identifiable), or is set to a function that returns an anonymized
- *   representation of this state.
+ * (`true` for anonymous, `false` if it has potential to be personally
+ * identifiable), or is set to a function that returns an anonymized
+ * representation of this state.
  */
 export interface StatePropertyMetadata<T extends Json> {
   persist: boolean | StateDeriver<T>;
@@ -101,12 +101,12 @@ export class BaseController<
   /**
    * Creates a BaseController instance.
    *
-   * @param options
-   * @param options.messenger - Controller messaging system
+   * @param options - Controller options.
+   * @param options.messenger - Controller messaging system.
    * @param options.metadata - State metadata, describing how to "anonymize" the state, and which
-   *   parts should be persisted.
-   * @param options.name - The name of the controller, used as a namespace for events and actions
-   * @param options.state - Initial controller state
+   * parts should be persisted.
+   * @param options.name - The name of the controller, used as a namespace for events and actions.
+   * @param options.state - Initial controller state.
    */
   constructor({
     messenger,
@@ -131,9 +131,9 @@ export class BaseController<
   }
 
   /**
-   * Retrieves current controller state
+   * Retrieves current controller state.
    *
-   * @returns - Current state
+   * @returns The current state.
    */
   get state() {
     return this.internalState;
@@ -152,7 +152,7 @@ export class BaseController<
    * applied to the controller state.
    *
    * @param callback - Callback for updating state, passed a draft state
-   *   object. Return a new state object or mutate the draft to update state.
+   * object. Return a new state object or mutate the draft to update state.
    */
   protected update(callback: (state: Draft<S>) => void | S) {
     // We run into ts2589, "infinite type depth", if we don't cast
@@ -193,10 +193,10 @@ export class BaseController<
  * By "anonymized" we mean that it should not contain any information that could be personally
  * identifiable.
  *
- * @param state - The controller state
+ * @param state - The controller state.
  * @param metadata - The controller state metadata, which describes how to derive the
- *   anonymized state
- * @returns The anonymized controller state
+ * anonymized state.
+ * @returns The anonymized controller state.
  */
 export function getAnonymizedState<S extends Record<string, Json>>(
   state: S,
@@ -206,11 +206,11 @@ export function getAnonymizedState<S extends Record<string, Json>>(
 }
 
 /**
- * Returns the subset of state that should be persisted
+ * Returns the subset of state that should be persisted.
  *
- * @param state - The controller state
- * @param metadata - The controller state metadata, which describes which pieces of state should be persisted
- * @returns The subset of controller state that should be persisted
+ * @param state - The controller state.
+ * @param metadata - The controller state metadata, which describes which pieces of state should be persisted.
+ * @returns The subset of controller state that should be persisted.
  */
 export function getPersistentState<S extends Record<string, Json>>(
   state: S,
@@ -219,6 +219,14 @@ export function getPersistentState<S extends Record<string, Json>>(
   return deriveStateFromMetadata(state, metadata, 'persist');
 }
 
+/**
+ * Use the metadata to derive state according to the given metadata property.
+ *
+ * @param state - The full controller state.
+ * @param metadata - The controller metadata.
+ * @param metadataProperty - The metadata property to use to derive state.
+ * @returns The metadata-derived controller state.
+ */
 function deriveStateFromMetadata<S extends Record<string, Json>>(
   state: S,
   metadata: StateMetadata<S>,

src/ComposableController.ts

@@ -35,10 +35,10 @@ export class ComposableController extends BaseController<never, any> {
   name = 'ComposableController';
 
   /**
-   * Creates a ComposableController instance
+   * Creates a ComposableController instance.
    *
-   * @param controllers - Map of names to controller instances
-   * @param messenger - The controller messaging system, used for communicating with BaseControllerV2 controllers
+   * @param controllers - Map of names to controller instances.
+   * @param messenger - The controller messaging system, used for communicating with BaseControllerV2 controllers.
    */
   constructor(
     controllers: ControllerList,
@@ -86,7 +86,7 @@ export class ComposableController extends BaseController<never, any> {
    * of controller name. Instead, all child controller state is merged
    * together into a single, flat object.
    *
-   * @returns - Merged state representation of all child controllers
+   * @returns Merged state representation of all child controllers.
    */
   get flatState() {
     let flatState = {};