use prettier-plugin-jsdoc (#4969)

* install and configure prettier-plugin-jsdoc

* format files using prettier-plugin-jsdoc

.prettierrc

@@ -5,5 +5,7 @@
   "semi": true,
   "singleQuote": true,
   "trailingComma": "none",
-  "bracketSpacing": true
+  "bracketSpacing": true,
+  "plugins": ["prettier-plugin-jsdoc"],
+  "tsdoc": true
 }

examples/todomvc-react/src/react-app-env.d.ts

@@ -9,11 +9,11 @@ declare namespace NodeJS {
     /**
      * By default, there are two modes in Vite:
      *
-     * * `development` is used by vite and vite serve
-     * * `production` is used by vite build
-     *
-     * You can overwrite the default mode used for a command by passing the --mode option flag.
+     * - `development` is used by vite and vite serve
+     * - `production` is used by vite build
      *
+     * You can overwrite the default mode used for a command by passing the
+     * --mode option flag.
      */
     readonly NODE_ENV: 'development' | 'production';
   }

jest.config.js

@@ -1,8 +1,6 @@
 const { constants } = require('jest-config');
 
-/**
- * @type {import('@jest/types').Config.InitialOptions}
- */
+/** @type {import('@jest/types').Config.InitialOptions} */
 module.exports = {
   prettierPath: null,
   setupFilesAfterEnv: ['@xstate-repo/jest-utils/setup'],

package.json

@@ -76,6 +76,7 @@
     "markdown-it-codesandbox-embed": "^0.1.0",
     "patch-package": "^6.5.1",
     "prettier": "^3.1.0",
+    "prettier-plugin-jsdoc": "^1.3.0",
     "spawn-command": "0.0.2-1",
     "synckit": "^0.8.5",
     "tslib": "^2.3.1",

packages/core/src/State.ts

@@ -55,9 +55,7 @@ interface MachineSnapshotBase<
   TMeta,
   _TUnusedButLeftForCompatReasons = never
 > {
-  /**
-   * The state machine that produced this state snapshot.
-   */
+  /** The state machine that produced this state snapshot. */
   machine: StateMachine<
     TContext,
     TEvent,
@@ -73,61 +71,59 @@ interface MachineSnapshotBase<
     EventObject, // TEmitted
     any // TMeta
   >;
-  /**
-   * The tags of the active state nodes that represent the current state value.
-   */
+  /** The tags of the active state nodes that represent the current state value. */
   tags: Set<string>;
   /**
    * The current state value.
    *
    * This represents the active state nodes in the state machine.
-   * - For atomic state nodes, it is a string. 
+   *
+   * - For atomic state nodes, it is a string.
    * - For compound parent state nodes, it is an object where:
+   *
    *   - The key is the parent state node's key
    *   - The value is the current state value of the active child state node(s)
-   * 
+   *
    * @example
-  ```ts
-  // single-level state node
-  snapshot.value; // => 'yellow'
-
-  // nested state nodes
-  snapshot.value; // => { red: 'wait' }
-  ```
+   *
+   * ```ts
+   * // single-level state node
+   * snapshot.value; // => 'yellow'
+   *
+   * // nested state nodes
+   * snapshot.value; // => { red: 'wait' }
+   * ```
    */
   value: TStateValue;
-  /**
-   * The current status of this snapshot.
-   */
+  /** The current status of this snapshot. */
   status: 'active' | 'done' | 'error' | 'stopped';
   error: unknown;
   context: TContext;
 
   historyValue: Readonly<HistoryValue<TContext, TEvent>>;
-  /**
-   * The enabled state nodes representative of the state value.
-   */
+  /** The enabled state nodes representative of the state value. */
   _nodes: Array<StateNode<TContext, TEvent>>;
-  /**
-   * An object mapping actor names to spawned/invoked actors.
-   */
+  /** An object mapping actor names to spawned/invoked actors. */
   children: TChildren;
 
   /**
-   * Whether the current state value is a subset of the given partial state value.
+   * Whether the current state value is a subset of the given partial state
+   * value.
+   *
    * @param partialStateValue
    */
   matches: (partialStateValue: ToTestStateValue<TStateValue>) => boolean;
 
   /**
    * Whether the current state nodes has a state node with the specified `tag`.
+   *
    * @param tag
    */
   hasTag: (tag: TTag) => boolean;
 
   /**
-   * Determines whether sending the `event` will cause a non-forbidden transition
-   * to be selected, even if the transitions have no actions nor
+   * Determines whether sending the `event` will cause a non-forbidden
+   * transition to be selected, even if the transitions have no actions nor
    * change the state value.
    *
    * @param event The event to test

packages/core/src/StateMachine.ts

@@ -84,9 +84,7 @@ export class StateMachine<
       TEmitted
     >
 {
-  /**
-   * The machine's own version.
-   */
+  /** The machine's own version. */
   public version?: string;
 
   public schemas: unknown;
@@ -107,9 +105,7 @@ export class StateMachine<
   public events: Array<EventDescriptor<TEvent>>;
 
   constructor(
-    /**
-     * The raw config used to create the machine.
-     */
+    /** The raw config used to create the machine. */
     public config: MachineConfig<
       TContext,
       TEvent,
@@ -167,12 +163,11 @@ export class StateMachine<
   }
 
   /**
-   * Clones this state machine with the provided implementations
-   * and merges the `context` (if provided).
-   *
-   * @param implementations Options (`actions`, `guards`, `actors`, `delays`, `context`)
-   *  to recursively merge with the existing options.
+   * Clones this state machine with the provided implementations and merges the
+   * `context` (if provided).
    *
+   * @param implementations Options (`actions`, `guards`, `actors`, `delays`,
+   *   `context`) to recursively merge with the existing options.
    * @returns A new `StateMachine` instance with the provided implementations.
    */
   public provide(
@@ -263,8 +258,8 @@ export class StateMachine<
   }
 
   /**
-   * Determines the next snapshot given the current `snapshot` and received `event`.
-   * Calculates a full macrostep from all microsteps.
+   * Determines the next snapshot given the current `snapshot` and received
+   * `event`. Calculates a full macrostep from all microsteps.
    *
    * @param snapshot The current snapshot
    * @param event The received event
@@ -294,8 +289,8 @@ export class StateMachine<
   }
 
   /**
-   * Determines the next state given the current `state` and `event`.
-   * Calculates a microstep.
+   * Determines the next state given the current `state` and `event`. Calculates
+   * a microstep.
    *
    * @param state The current state
    * @param event The received event
@@ -342,8 +337,8 @@ export class StateMachine<
   }
 
   /**
-   * The initial state _before_ evaluating any microsteps.
-   * This "pre-initial" state is provided to initial actions executed in the initial state.
+   * The initial state _before_ evaluating any microsteps. This "pre-initial"
+   * state is provided to initial actions executed in the initial state.
    */
   private getPreInitialState(
     actorScope: AnyActorScope,
@@ -387,7 +382,8 @@ export class StateMachine<
   }
 
   /**
-   * Returns the initial `State` instance, with reference to `self` as an `ActorRef`.
+   * Returns the initial `State` instance, with reference to `self` as an
+   * `ActorRef`.
    */
   public getInitialSnapshot(
     actorScope: ActorScope<

packages/core/src/StateNode.ts

@@ -70,53 +70,40 @@ export class StateNode<
   TEvent extends EventObject = EventObject
 > {
   /**
-   * The relative key of the state node, which represents its location in the overall state value.
+   * The relative key of the state node, which represents its location in the
+   * overall state value.
    */
   public key: string;
-  /**
-   * The unique ID of the state node.
-   */
+  /** The unique ID of the state node. */
   public id: string;
   /**
    * The type of this state node:
    *
-   *  - `'atomic'` - no child state nodes
-   *  - `'compound'` - nested child state nodes (XOR)
-   *  - `'parallel'` - orthogonal nested child state nodes (AND)
-   *  - `'history'` - history state node
-   *  - `'final'` - final state node
+   * - `'atomic'` - no child state nodes
+   * - `'compound'` - nested child state nodes (XOR)
+   * - `'parallel'` - orthogonal nested child state nodes (AND)
+   * - `'history'` - history state node
+   * - `'final'` - final state node
    */
   public type: 'atomic' | 'compound' | 'parallel' | 'final' | 'history';
-  /**
-   * The string path from the root machine node to this node.
-   */
+  /** The string path from the root machine node to this node. */
   public path: string[];
-  /**
-   * The child state nodes.
-   */
+  /** The child state nodes. */
   public states: StateNodesConfig<TContext, TEvent>;
   /**
    * The type of history on this state node. Can be:
    *
-   *  - `'shallow'` - recalls only top-level historical state value
-   *  - `'deep'` - recalls historical state value at all levels
+   * - `'shallow'` - recalls only top-level historical state value
+   * - `'deep'` - recalls historical state value at all levels
    */
   public history: false | 'shallow' | 'deep';
-  /**
-   * The action(s) to be executed upon entering the state node.
-   */
+  /** The action(s) to be executed upon entering the state node. */
   public entry: UnknownAction[];
-  /**
-   * The action(s) to be executed upon exiting the state node.
-   */
+  /** The action(s) to be executed upon exiting the state node. */
   public exit: UnknownAction[];
-  /**
-   * The parent state node.
-   */
+  /** The parent state node. */
   public parent?: StateNode<TContext, TEvent>;
-  /**
-   * The root machine node.
-   */
+  /** The root machine node. */
   public machine: StateMachine<
     TContext,
     TEvent,
@@ -133,18 +120,21 @@ export class StateNode<
     any // meta
   >;
   /**
-   * The meta data associated with this state node, which will be returned in State instances.
+   * The meta data associated with this state node, which will be returned in
+   * State instances.
    */
   public meta?: any;
   /**
-   * The output data sent with the "xstate.done.state._id_" event if this is a final state node.
+   * The output data sent with the "xstate.done.state._id_" event if this is a
+   * final state node.
    */
   public output?:
     | Mapper<MachineContext, EventObject, unknown, EventObject>
     | NonReducibleUnknown;
 
   /**
-   * The order this state node appears. Corresponds to the implicit document order.
+   * The order this state node appears. Corresponds to the implicit document
+   * order.
    */
   public order: number = -1;
 
@@ -155,9 +145,7 @@ export class StateNode<
   public always?: Array<TransitionDefinition<TContext, TEvent>>;
 
   constructor(
-    /**
-     * The raw config used to create the machine.
-     */
+    /** The raw config used to create the machine. */
     public config: StateNodeConfig<
       TContext,
       TEvent,
@@ -243,9 +231,7 @@ export class StateNode<
     });
   }
 
-  /**
-   * The well-structured state node definition.
-   */
+  /** The well-structured state node definition. */
   public get definition(): StateNodeDefinition<TContext, TEvent> {
     return {
       id: this.id,
@@ -292,9 +278,7 @@ export class StateNode<
     return this.definition;
   }
 
-  /**
-   * The logic invoked as actors by this state node.
-   */
+  /** The logic invoked as actors by this state node. */
   public get invoke(): Array<
     InvokeDefinition<
       TContext,
@@ -343,9 +327,7 @@ export class StateNode<
     );
   }
 
-  /**
-   * The mapping of events to transitions.
-   */
+  /** The mapping of events to transitions. */
   public get on(): TransitionDefinitionMap<TContext, TEvent> {
     return memo(this, 'on', () => {
       const transitions = this.transitions;
@@ -442,9 +424,7 @@ export class StateNode<
     return selectedTransition ? [selectedTransition] : undefined;
   }
 
-  /**
-   * All the event types accepted by this state node and its descendants.
-   */
+  /** All the event types accepted by this state node and its descendants. */
   public get events(): Array<EventDescriptor<TEvent>> {
     return memo(this, 'events', () => {
       const { states } = this;