@serenity-js/core 3.25.0 → 3.25.2

package/src/stage/Stage.ts

@@ -22,17 +22,18 @@ import type { Cast } from './Cast';
 import type { StageManager } from './StageManager';
 
 /**
- * Stage is the place where {@apilink Actor|actors} perform.
+ * Stage is the place where [actors](https://serenity-js.org/api/core/class/Actor/) perform.
  *
- * In more technical terms, the Stage is the main event bus propagating {@apilink DomainEvent|DomainEvents}
- * to {@apilink Actor|Actors} it instantiates and {@apilink StageCrewMember|StageCrewMembers} that have been registered with it.
+ * In more technical terms, the Stage is the main event bus propagating [Serenity/JS domain events](https://serenity-js.org/api/core-events/class/DomainEvent/)
+ * to [actors](https://serenity-js.org/api/core/class/Actor/) it instantiates and [stage crew members](https://serenity-js.org/api/core/interface/StageCrewMember/) that have been registered with it.
  *
  * It is unlikely that you'll ever need to interact with the `Stage` directly in your tests. Instead, you'll use functions like
- * {@apilink actorCalled} and {@apilink actorInTheSpotlight}.
+ * [`actorCalled`](https://serenity-js.org/api/core/function/actorCalled/) and [`actorInTheSpotlight`](https://serenity-js.org/api/core/function/actorInTheSpotlight/).
  *
  * ## Learn more
- * - {@apilink configure}
- * - {@apilink engage}
+ * - [`configure`](https://serenity-js.org/api/core/function/configure/)
+ * - [`engage`](https://serenity-js.org/api/core/function/engage/)
+ * - [`StageCrewMember`](https://serenity-js.org/api/core/interface/StageCrewMember/)
  *
  * @group Stage
  */
@@ -55,7 +56,7 @@ export class Stage implements EmitsDomainEvents {
     private actorsOnStage: Map<string, Actor> = this.actorsOnBackstage;
 
     /**
-     * The most recent actor referenced via the {@apilink actor} method
+     * The most recent actor referenced via the [`Actor`](https://serenity-js.org/api/core/class/Actor/) method
      */
     private actorInTheSpotlight: Actor = undefined;
 
@@ -85,7 +86,7 @@ export class Stage implements EmitsDomainEvents {
     }
 
     /**
-     * An alias for {@apilink Stage.actor}
+     * An alias for [`Stage.actor`](https://serenity-js.org/api/core/class/Stage/#actor)
      *
      * @param name
      */
@@ -94,7 +95,7 @@ export class Stage implements EmitsDomainEvents {
     }
 
     /**
-     * Instantiates a new {@apilink Actor} or fetches an existing one
+     * Instantiates a new [`Actor`](https://serenity-js.org/api/core/class/Actor/) or fetches an existing one
      * identified by their name if they've already been instantiated.
      *
      * @param name
@@ -131,11 +132,11 @@ export class Stage implements EmitsDomainEvents {
     }
 
     /**
-     * Returns the last {@apilink Actor} instantiated via {@apilink Stage.actor}.
+     * Returns the last [`Actor`](https://serenity-js.org/api/core/class/Actor/) instantiated via [`Stage.actor`](https://serenity-js.org/api/core/class/Stage/#actor).
      * Useful when you don't can't or choose not to reference the actor by their name.
      *
-     * @throws {LogicError}
-     *  If no {@apilink Actor} has been activated yet
+     * @throws [`LogicError`](https://serenity-js.org/api/core/class/LogicError/)
+     *  If no [`Actor`](https://serenity-js.org/api/core/class/Actor/) has been activated yet
      */
     theActorInTheSpotlight(): Actor {
         if (! this.actorInTheSpotlight) {
@@ -146,15 +147,15 @@ export class Stage implements EmitsDomainEvents {
     }
 
     /**
-     * Returns `true` if there is an {@apilink Actor} in the spotlight, `false` otherwise.
+     * Returns `true` if there is an [`Actor`](https://serenity-js.org/api/core/class/Actor/) in the spotlight, `false` otherwise.
      */
     theShowHasStarted(): boolean {
         return !! this.actorInTheSpotlight;
     }
 
     /**
-     * Configures the Stage to prepare {@apilink Actor|Actors}
-     * instantiated via {@apilink Stage.actor} using the provided {@apilink Cast}.
+     * Configures the Stage to prepare [actors](https://serenity-js.org/api/core/class/Actor/)
+     * instantiated via [`Stage.actor`](https://serenity-js.org/api/core/class/Stage/#actor) using the provided [cast](https://serenity-js.org/api/core/class/Cast/).
      *
      * @param actors
      */
@@ -165,8 +166,8 @@ export class Stage implements EmitsDomainEvents {
     }
 
     /**
-     * Assigns listeners to be notified of {@apilink DomainEvent|DomainEvents}
-     * emitted via {@apilink Stage.announce}.s
+     * Assigns listeners to be notified of [Serenity/JS domain events](https://serenity-js.org/api/core-events/class/DomainEvent/)
+     * emitted via [`Stage.announce`](https://serenity-js.org/api/core/class/Stage/#announce).s
      *
      * @param listeners
      */
@@ -206,22 +207,21 @@ export class Stage implements EmitsDomainEvents {
 
     /**
      * Returns current time. This method should be used whenever
-     * {@apilink DomainEvent} objects are instantiated by you programmatically.
+     * [`DomainEvent`](https://serenity-js.org/api/core-events/class/DomainEvent/) objects are instantiated by you programmatically.
      */
     currentTime(): Timestamp {
         return this.manager.currentTime();
     }
 
     /**
-     * Generates and remembers a {@apilink CorrelationId}
+     * Generates and remembers a `CorrelationId`
      * for the current scene.
      *
      * This method should be used in custom test runner adapters
-     * when instantiating a {@apilink SceneStarts} event.
+     * when instantiating a [SceneStarts](https://serenity-js.org/api/core-events/class/SceneStarts/) event.
      *
      * #### Learn more
-     * - {@apilink Stage.currentSceneId}
-     * - {@apilink CorrelationId}
+     * - [`Stage.currentSceneId`](https://serenity-js.org/api/core/class/Stage/#currentSceneId)
      */
     assignNewSceneId(): CorrelationId {
         // todo: inject an id factory to make it easier to test
@@ -231,24 +231,24 @@ export class Stage implements EmitsDomainEvents {
     }
 
     /**
-     * Returns the {@apilink CorrelationId} for the current scene.
+     * Returns the `CorrelationId` for the current scene.
      *
      * #### Learn more
-     * - {@apilink Stage.assignNewSceneId}
+     * - [`Stage.assignNewSceneId`](https://serenity-js.org/api/core/class/Stage/#assignNewSceneId)
      */
     currentSceneId(): CorrelationId {
         return this.currentScene;
     }
 
     /**
-     * Generates and remembers a {@apilink CorrelationId}
-     * for the current {@apilink Activity}.
+     * Generates and remembers a `CorrelationId`
+     * for the current [`Activity`](https://serenity-js.org/api/core/class/Activity/).
      *
      * This method should be used in custom test runner adapters
-     * when instantiating the {@apilink ActivityStarts} event.
+     * when instantiating the [ActivityStarts](https://serenity-js.org/api/core-events/class/ActivityStarts/) event.
      *
      * #### Learn more
-     * - {@apilink Stage.currentActivityId}
+     * - [`Stage.currentActivityId`](https://serenity-js.org/api/core/class/Stage/#currentActivityId)
      */
     assignNewActivityId(activityDetails: ActivityDetails): CorrelationId {
         this.currentActivity = {
@@ -260,10 +260,10 @@ export class Stage implements EmitsDomainEvents {
     }
 
     /**
-     * Returns the {@apilink CorrelationId} for the current {@apilink Activity}.
+     * Returns the `CorrelationId` for the current [`Activity`](https://serenity-js.org/api/core/class/Activity/).
      *
      * #### Learn more
-     * - {@apilink Stage.assignNewSceneId}
+     * - [`Stage.assignNewSceneId`](https://serenity-js.org/api/core/class/Stage/#assignNewSceneId)
      */
     currentActivityId(): CorrelationId {
         if (! this.currentActivity) {

package/src/stage/StageCrewMember.ts

@@ -2,12 +2,12 @@ import type { ListensToDomainEvents } from './ListensToDomainEvents';
 import type { Stage } from './Stage';
 
 /**
- * You can think of the {@apilink StageCrewMember} as an in-memory microservice that reacts to {@apilink DomainEvent|domain events},
- * published by the {@apilink StageManager}, and originally emitted by {@apilink Actor|actors} performing activities and Serenity/JS
- * test runner adapters notifying the framework about test scenario-specific events like {@apilink SceneStarts} or {@apilink SceneFinishes}.
+ * You can think of the [`StageCrewMember`](https://serenity-js.org/api/core/interface/StageCrewMember/) as an in-memory microservice that reacts to [Serenity/JS domain events](https://serenity-js.org/api/core-events/class/DomainEvent/),
+ * published by the [`StageManager`](https://serenity-js.org/api/core/class/StageManager/), and originally emitted by [actors](https://serenity-js.org/api/core/class/Actor/) performing activities and Serenity/JS
+ * test runner adapters notifying the framework about test scenario-specific events like [SceneStarts](https://serenity-js.org/api/core-events/class/SceneStarts/) or [SceneFinishes](https://serenity-js.org/api/core-events/class/SceneFinishes/).
  *
- * Every {@apilink StageCrewMember} receives a reference to the {@apilink Stage},
- * and therefore {@apilink StageManager} as well, which enables them to emit {@apilink DomainEvent}s back.
+ * Every [stage crew member](https://serenity-js.org/api/core/interface/StageCrewMember/) receives a reference to the [stage](https://serenity-js.org/api/core/class/Stage/),
+ * and therefore the [stage manager](https://serenity-js.org/api/core/class/StageManager/), which enables them to emit [domain events](https://serenity-js.org/api/core-events/class/DomainEvent/) back.
  *
  * This interface is useful when you're interested in implementing custom Serenity/JS reporters or supporting services.
  *
@@ -62,18 +62,18 @@ import type { Stage } from './Stage';
  * ```
  *
  * ## Learn more
- * - {@apilink SerenityConfig.crew}
- * - {@apilink configure}
- * - {@apilink StageCrewMemberBuilder}
- * - {@apilink ListensToDomainEvents}
- * - {@apilink DomainEvent}
+ * - [`SerenityConfig.crew`](https://serenity-js.org/api/core/class/SerenityConfig/#crew)
+ * - [`configure`](https://serenity-js.org/api/core/function/configure/)
+ * - [`StageCrewMember`](https://serenity-js.org/api/core/interface/StageCrewMemberBuilder/)
+ * - [`ListensToDomainEvents`](https://serenity-js.org/api/core/interface/ListensToDomainEvents/)
+ * - [`DomainEvent`](https://serenity-js.org/api/core-events/class/DomainEvent/)
  *
  * @group Stage
  */
 export interface StageCrewMember extends ListensToDomainEvents {
 
     /**
-     * Assigns a {@apilink Stage} to this {@apilink StageCrewMember}
+     * Assigns a [`Stage`](https://serenity-js.org/api/core/class/Stage/) to this [`StageCrewMember`](https://serenity-js.org/api/core/interface/StageCrewMember/)
      */
     assignedTo(stage: Stage): StageCrewMember;
 }

package/src/stage/StageCrewMemberBuilder.ts

@@ -2,23 +2,23 @@ import type { ListensToDomainEvents } from './ListensToDomainEvents';
 import type { StageCrewMemberBuilderDependencies } from './StageCrewMemberBuilderDependencies';
 
 /**
- * Use a {@apilink StageCrewMemberBuilder} to configure complex {@apilink StageCrewMember} objects.
+ * Use a [`StageCrewMember`](https://serenity-js.org/api/core/interface/StageCrewMemberBuilder/) to configure complex [`StageCrewMember`](https://serenity-js.org/api/core/interface/StageCrewMember/) objects.
  *
  * Useful when you're interested in implementing custom reporters with multiple configuration options.
- * See {@apilink ConsoleReporter} for an example.
+ * See [`ConsoleReporter`](https://serenity-js.org/api/console-reporter/class/ConsoleReporter/) for an example.
  *
  * ## Learn more
- * - {@apilink StageCrewMember}
- * - {@apilink StageCrewMemberBuilderDependencies}
- * - {@apilink SerenityConfig.crew}
+ * - [`StageCrewMember`](https://serenity-js.org/api/core/interface/StageCrewMember/)
+ * - [`StageCrewMemberBuilderDependencies`](https://serenity-js.org/api/core/interface/StageCrewMemberBuilderDependencies/)
+ * - [`SerenityConfig.crew`](https://serenity-js.org/api/core/class/SerenityConfig/#crew)
  *
  * @group Stage
  */
 export interface StageCrewMemberBuilder<T extends ListensToDomainEvents = ListensToDomainEvents> {
 
     /**
-     * Instantiates a {@apilink StageCrewMember}, giving it access to shared dependencies
-     * such as {@apilink Stage} or {@apilink OutputStream}
+     * Instantiates a [`StageCrewMember`](https://serenity-js.org/api/core/interface/StageCrewMember/), giving it access to shared dependencies
+     * such as [`Stage`](https://serenity-js.org/api/core/class/Stage/) or [`OutputStream`](https://serenity-js.org/api/core-adapter/interface/OutputStream/)
      */
     build(dependencies: StageCrewMemberBuilderDependencies): T;
 }

package/src/stage/StageCrewMemberBuilderDependencies.ts

@@ -3,10 +3,10 @@ import type { FileSystem } from '../io';
 import type { Stage } from './Stage';
 
 /**
- * Dependencies injected by {@apilink Serenity.configure} into {@apilink StageCrewMemberBuilder.build}
+ * Dependencies injected by [`Serenity.configure`](https://serenity-js.org/api/core/class/Serenity/#configure) into [`StageCrewMemberBuilder.build`](https://serenity-js.org/api/core/interface/StageCrewMemberBuilder/#build)
  *
  * ## Learn more
- * - {@apilink StageCrewMemberBuilder}
+ * - [`StageCrewMember`](https://serenity-js.org/api/core/interface/StageCrewMemberBuilder/)
  *
  * @group Stage
  */

package/src/stage/crew/artifact-archiver/ArtifactArchiver.ts

@@ -20,7 +20,7 @@ import type { StageCrewMember } from '../../StageCrewMember';
 import { Hash } from './Hash';
 
 /**
- * Stores any {@apilink Artifact|artifacts} emitted via {@apilink ArtifactGenerated} events on the {@apilink FileSystem}.
+ * Stores any artifacts emitted via [`ArtifactGenerated`](https://serenity-js.org/api/core-events/class/ArtifactGenerated/) events on the file system.
  *
  * ## Registering Artifact Archiver programmatically
  *
@@ -130,7 +130,7 @@ export class ArtifactArchiver implements StageCrewMember {
     /**
      * @param {FileSystem} fileSystem
      * @param {Stage} [stage]
-     *  The stage this {@apilink StageCrewMember} should be assigned to
+     *  The stage this [`StageCrewMember`](https://serenity-js.org/api/core/interface/StageCrewMember/) should be assigned to
      */
     constructor(
         private readonly fileSystem: FileSystem,
@@ -144,9 +144,9 @@ export class ArtifactArchiver implements StageCrewMember {
     }
 
     /**
-     * Handles {@apilink DomainEvent} objects emitted by the {@apilink StageManager}.
+     * Handles [`DomainEvent`](https://serenity-js.org/api/core-events/class/DomainEvent/) objects emitted by the [`StageManager`](https://serenity-js.org/api/core/class/StageManager/).
      *
-     * @see {@apilink StageCrewMember}
+     * @see [`StageCrewMember`](https://serenity-js.org/api/core/interface/StageCrewMember/)
      *
      * @listens {ArtifactGenerated}
      * @emits {ArtifactArchived}

package/src/stage/crew/stream-reporter/StreamReporter.ts

@@ -7,7 +7,7 @@ import type { Stage } from '../../Stage';
 import type { StageCrewMember } from '../../StageCrewMember';
 
 /**
- * Serialises all the {@apilink DomainEvent} objects it receives and streams
+ * Serialises all the [`DomainEvent`](https://serenity-js.org/api/core-events/class/DomainEvent/) objects it receives and streams
  * them as [ndjson](http://ndjson.org/) to the output stream or file.
  *
  * Useful when debugging issues related to custom Serenity/JS test runner adapters.
@@ -101,7 +101,7 @@ import type { StageCrewMember } from '../../StageCrewMember';
 export class StreamReporter implements StageCrewMember {
 
     /**
-     * Instantiates a `StreamReporter` outputting a stream of {@apilink DomainEvent|domain events}
+     * Instantiates a `StreamReporter` outputting a stream of [Serenity/JS domain events](https://serenity-js.org/api/core-events/class/DomainEvent/)
      * to an `outputFile` at the given location.
      *
      * @param config
@@ -120,7 +120,7 @@ export class StreamReporter implements StageCrewMember {
      *  A Writable stream that should receive the output
      *
      * @param {Stage} [stage]
-     *  The stage this {@apilink StageCrewMember} should be assigned to
+     *  The stage this [`StageCrewMember`](https://serenity-js.org/api/core/interface/StageCrewMember/) should be assigned to
      */
     constructor(
         private readonly output: Writable = process.stdout,
@@ -129,20 +129,20 @@ export class StreamReporter implements StageCrewMember {
     }
 
     /**
-     * Creates a new instance of this {@apilink StageCrewMember} and assigns it to a given {@apilink Stage}.
+     * Creates a new instance of this [`StageCrewMember`](https://serenity-js.org/api/core/interface/StageCrewMember/) and assigns it to a given [`Stage`](https://serenity-js.org/api/core/class/Stage/).
      *
      * @param stage
-     *  An instance of a {@apilink Stage} this {@apilink StageCrewMember} will be assigned to
+     *  An instance of a [`Stage`](https://serenity-js.org/api/core/class/Stage/) this [`StageCrewMember`](https://serenity-js.org/api/core/interface/StageCrewMember/) will be assigned to
      *
      * @returns {StageCrewMember}
-     *  A new instance of this {@apilink StageCrewMember}
+     *  A new instance of this [`StageCrewMember`](https://serenity-js.org/api/core/interface/StageCrewMember/)
      */
     assignedTo(stage: Stage): StageCrewMember {
         return new StreamReporter(this.output, stage);
     }
 
     /**
-     * Handles {@apilink DomainEvent} objects emitted by the {@apilink StageManager}.
+     * Handles [`DomainEvent`](https://serenity-js.org/api/core-events/class/DomainEvent/) objects emitted by the [`StageManager`](https://serenity-js.org/api/core/class/StageManager/).
      *
      * @listens {DomainEvent}
      *