@serenity-js/core 3.25.0 → 3.25.2

package/src/config/SerenityConfig.ts

@@ -5,41 +5,41 @@ import type { Cast, StageCrewMember, StageCrewMemberBuilder } from '../stage';
 import type { ClassDescription } from './ClassDescription';
 
 /**
- * Describes the configuration object accepted by the {@apilink configure} function.
+ * Describes the configuration object accepted by the [`configure`](https://serenity-js.org/api/core/function/configure/) function.
  *
  * ## Learn more
- * - {@apilink configure}
- * - {@apilink Cast}
- * - {@apilink StageCrewMember}
- * - {@apilink StageCrewMemberBuilder}
- * - {@apilink ClassDescription}
- * - {@apilink Stage.waitForNextCue}
+ * - [`configure`](https://serenity-js.org/api/core/function/configure/)
+ * - [`Cast`](https://serenity-js.org/api/core/class/Cast/)
+ * - [`StageCrewMember`](https://serenity-js.org/api/core/interface/StageCrewMember/)
+ * - [`StageCrewMember`](https://serenity-js.org/api/core/interface/StageCrewMemberBuilder/)
+ * - [`ClassDescription`](https://serenity-js.org/api/core/#ClassDescription)
+ * - [`Stage.waitForNextCue`](https://serenity-js.org/api/core/class/Stage/#waitForNextCue)
  *
  * @group Serenity
  */
 export abstract class SerenityConfig {
 
     /**
-     * A {@apilink Cast} of {@apilink Actor}s to be used when {@apilink actorCalled}
-     * and {@apilink actorInTheSpotlight} functions are called.
+     * A [cast](https://serenity-js.org/api/core/class/Cast/) of [actors](https://serenity-js.org/api/core/class/Actor/) to be used when [`actorCalled`](https://serenity-js.org/api/core/function/actorCalled/)
+     * and [`actorInTheSpotlight`](https://serenity-js.org/api/core/function/actorInTheSpotlight/) functions are called.
      */
     actors?: Cast;
 
     /**
-     * A list of {@apilink StageCrewMemberBuilder|StageCrewMemberBuilders} or {@apilink StageCrewMember|StageCrewMembers}
-     * to be notified of {@apilink DomainEvent|DomainEvents} that occur during the scenario execution.
+     * A list of [stage crew member builders](https://serenity-js.org/api/core/interface/StageCrewMemberBuilder/) or [stage crew members](https://serenity-js.org/api/core/interface/StageCrewMember/)
+     * to be notified of [Serenity/JS domain events](https://serenity-js.org/api/core-events/class/DomainEvent/) that occur during the scenario execution.
      *
-     * Note that the `crew` can also be configured using {@apilink ClassDescription|ClassDescriptions}.
+     * Note that the `crew` can also be configured using [class descriptions](https://serenity-js.org/api/core/#ClassDescription).
      * This is useful when you need to load the configuration from a static `json` file, or when the test runner doesn't support
      * providing class instances in configuration (e.g. Playwright Test).
      */
     crew?: Array<StageCrewMember | StageCrewMemberBuilder | ClassDescription>;
 
     /**
-     * The maximum amount of time between {@apilink SceneFinishes} and {@apilink SceneFinished} events
+     * The maximum amount of time between [SceneFinishes](https://serenity-js.org/api/core-events/class/SceneFinishes/) and [SceneFinished](https://serenity-js.org/api/core-events/class/SceneFinished/) events
      * that Serenity/JS should wait for any post-scenario
      * async operations to complete. Those include generating the screenshots,
-     * saving reports to disk, {@apilink Discardable|dismissing the actors}, and so on.
+     * saving reports to disk, [dismissing the actors](https://serenity-js.org/api/core/interface/Discardable/), and so on.
      *
      * Defaults to 5 seconds.
      *
@@ -49,7 +49,7 @@ export abstract class SerenityConfig {
     cueTimeout?: Duration;
 
     /**
-     * The maximum default amount of time allowed for interactions such as {@apilink Wait.until}
+     * The maximum default amount of time allowed for interactions such as [`Wait.until`](https://serenity-js.org/api/core/class/Wait/#until)
      * to complete.
      *
      * Defaults to 5 seconds, can be overridden per interaction.
@@ -58,20 +58,22 @@ export abstract class SerenityConfig {
      * a scenario timeout, which should be configured in your test runner.
      *
      * #### Learn more
-     * - {@apilink Wait.until}
+     * - [`Wait.until`](https://serenity-js.org/api/core/class/Wait/#until)
      */
     interactionTimeout?: Duration;
 
     /**
-     * {@apilink DiffFormatter} that should be used by the {@apilink ErrorFactory} and the ability to {@apilink RaiseErrors}
-     * when generating diffs included in {@apilink RuntimeError} objects.
+     * [`DiffFormatter`](https://serenity-js.org/api/core/interface/DiffFormatter/) that
+     * should be used by the [`ErrorFactory`](https://serenity-js.org/api/core/class/ErrorFactory/) and the ability
+     * to [`RaiseErrors`](https://serenity-js.org/api/core/class/RaiseErrors/)
+     * when generating diffs included in [`RuntimeError`](https://serenity-js.org/api/core/class/RuntimeError/) objects.
      *
-     * By default, Serenity/JS uses {@apilink NoOpDiffFormatter}.
+     * By default, Serenity/JS uses [`NoOpDiffFormatter`](https://serenity-js.org/api/core/class/NoOpDiffFormatter/)
      */
     diffFormatter?: DiffFormatter;
 
     /**
-     * An output stream to be injected into {@apilink StageCrewMemberBuilder|StageCrewMemberBuilders}
+     * An output stream to be injected into [stage crew member builders](https://serenity-js.org/api/core/interface/StageCrewMemberBuilder/)
      *
      * Defaults to [`process.stdout`](https://nodejs.org/api/process.html#process_process_stdout).
      */

package/src/errors/ErrorFactory.ts

@@ -11,7 +11,8 @@ import type { ErrorOptions } from './ErrorOptions';
 import type { RuntimeError } from './model';
 
 /**
- * Generates Serenity/JS {@apilink RuntimeError} objects based on provided {@apilink ErrorOptions|configuration}.
+ * Generates Serenity/JS [`RuntimeError`](https://serenity-js.org/api/core/class/RuntimeError/) objects based
+ * on the provided [configuration](https://serenity-js.org/api/core/interface/ErrorOptions/).
  *
  * @group Errors
  */

package/src/errors/ErrorSerialiser.ts

@@ -91,17 +91,17 @@ export class ErrorSerialiser {
 interface SerialisedError extends JSONObject {
     /**
      *  Name of the constructor function used to instantiate
-     *  the original {@apilink Error} object.
+     *  the original [`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) object.
      */
     name:    string;
 
     /**
-     *  Message of the original {@apilink Error} object
+     *  Message of the original [`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) object
      */
     message: string;
 
     /**
-     *  Stack trace of the original {@apilink Error} object
+     *  Stack trace of the original [`Error`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error) object
      */
     stack:   string;
 }

package/src/errors/RaiseErrors.ts

@@ -4,8 +4,8 @@ import type { ErrorOptions } from './ErrorOptions';
 import type { RuntimeError } from './model/RuntimeError';
 
 /**
- * An {@apilink Ability} that enables an {@apilink Actor} to create a Serenity/JS {@apilink RuntimeError}
- * from within a custom {@apilink Interaction}.
+ * An [`Ability`](https://serenity-js.org/api/core/class/Ability/) that enables an [`Actor`](https://serenity-js.org/api/core/class/Actor/) to create a Serenity/JS [`RuntimeError`](https://serenity-js.org/api/core/class/RuntimeError/)
+ * from within a custom [`Interaction`](https://serenity-js.org/api/core/class/Interaction/).
  *
  * The stack trace of an error created this way includes the filesystem location pointing to where the interaction was invoked,
  * which makes debugging any failures easier.
@@ -40,13 +40,13 @@ import type { RuntimeError } from './model/RuntimeError';
  * ```
  *
  * ## Learn more
- * - {@apilink ErrorOptions}
- * - {@apilink ErrorFactory}
- * - {@apilink AssertionError}
- * - {@apilink ConfigurationError}
- * - {@apilink LogicError}
- * - {@apilink RuntimeError}
- * - {@apilink TestCompromisedError}
+ * - [`ErrorOptions`](https://serenity-js.org/api/core/interface/ErrorOptions/)
+ * - [`ErrorFactory`](https://serenity-js.org/api/core/class/ErrorFactory/)
+ * - [`AssertionError`](https://serenity-js.org/api/core/class/AssertionError/)
+ * - [`ConfigurationError`](https://serenity-js.org/api/core/class/ConfigurationError/)
+ * - [`LogicError`](https://serenity-js.org/api/core/class/LogicError/)
+ * - [`RuntimeError`](https://serenity-js.org/api/core/class/RuntimeError/)
+ * - [`TestCompromisedError`](https://serenity-js.org/api/core/class/TestCompromisedError/)
  *
  * @group Errors
  */

package/src/errors/diff/AnsiDiffFormatter.ts

@@ -4,7 +4,7 @@ import { Instance as ChalkInstance } from 'chalk';   // eslint-disable-line unic
 import type { DiffFormatter } from './DiffFormatter';
 
 /**
- * A {@apilink DiffFormatter} that uses [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code)
+ * A [`DiffFormatter`](https://serenity-js.org/api/core/interface/DiffFormatter/) that uses [ANSI escape codes](https://en.wikipedia.org/wiki/ANSI_escape_code)
  * to format the output.
  *
  * @group Errors

package/src/errors/diff/DiffFormatter.ts

@@ -1,6 +1,6 @@
 /**
  * Formats text representing expected, received, and unchanged lines of a diff
- * produced by the {@apilink ErrorFactory}, so that they can be presented to a developer
+ * produced by the [`ErrorFactory`](https://serenity-js.org/api/core/class/ErrorFactory/), so that they can be presented to a developer
  * in a visually distinctive way.
  *
  * @group Errors

package/src/errors/diff/NoOpDiffFormatter.ts

@@ -1,7 +1,7 @@
 import type { DiffFormatter } from './DiffFormatter';
 
 /**
- * A no-op {@apilink DiffFormatter} that produces output identical to input.
+ * A no-op [`DiffFormatter`](https://serenity-js.org/api/core/interface/DiffFormatter/) that produces output identical to input.
  *
  * @group Errors
  */

package/src/errors/model/AssertionError.ts

@@ -23,7 +23,7 @@ export class AssertionError extends RuntimeError {
 
     /**
      * @param message - Human-readable description of the error and the difference between the expected and actual values
-     * @param [cause] - The root cause of this {@apilink RuntimeError}, if any
+     * @param [cause] - The root cause of this [`RuntimeError`](https://serenity-js.org/api/core/class/RuntimeError/), if any
      */
     constructor(message: string, cause?: Error) {
         super(AssertionError, message, cause);

package/src/errors/model/ConfigurationError.ts

@@ -23,7 +23,7 @@ export class ConfigurationError extends RuntimeError {
 
     /**
      * @param message - Human-readable description of the error
-     * @param [cause] - The root cause of this {@apilink RuntimeError}, if any
+     * @param [cause] - The root cause of this [`RuntimeError`](https://serenity-js.org/api/core/class/RuntimeError/), if any
      */
     constructor(message: string, cause?: Error) {
         super(ConfigurationError, message, cause);

package/src/errors/model/ImplementationPendingError.ts

@@ -4,8 +4,8 @@ import { ErrorSerialiser } from '../ErrorSerialiser';
 import { RuntimeError } from './RuntimeError';
 
 /**
- * Thrown to indicate that the {@apilink Actor} attempted to perform
- * a {@apilink Task} or {@apilink Interaction} that hasn't been implemented yet.
+ * Thrown to indicate that the [`Actor`](https://serenity-js.org/api/core/class/Actor/) attempted to perform
+ * a [`Task`](https://serenity-js.org/api/core/class/Task/) or [`Interaction`](https://serenity-js.org/api/core/class/Interaction/) that hasn't been implemented yet.
  *
  * ## A pending Task
  *
@@ -44,7 +44,7 @@ export class ImplementationPendingError extends RuntimeError {
 
     /**
      * @param {string} message - Human-readable description of the error
-     * @param {Error} [cause] - The root cause of this {@apilink RuntimeError}, if any
+     * @param {Error} [cause] - The root cause of this [`RuntimeError`](https://serenity-js.org/api/core/class/RuntimeError/), if any
      */
     constructor(message: string, cause?: Error) {
         super(ImplementationPendingError, message, cause);

package/src/errors/model/ListItemNotFoundError.ts

@@ -4,7 +4,7 @@ import { ErrorSerialiser } from '../ErrorSerialiser';
 import { RuntimeError } from './RuntimeError';
 
 /**
- * Thrown to indicate that an {@apilink Interaction}, a {@apilink Task} or a test scenario
+ * Thrown to indicate that an [`Interaction`](https://serenity-js.org/api/core/class/Interaction/), a [`Task`](https://serenity-js.org/api/core/class/Task/) or a test scenario
  * can't be executed due to no items are found in a list.
  *
  * For example, it's not possible to get the first() or the last() item of a list
@@ -27,7 +27,7 @@ export class ListItemNotFoundError extends RuntimeError {
 
     /**
      * @param message - Human-readable description of the error
-     * @param [cause] - The root cause of this {@apilink ListItemNotFoundError}, if any
+     * @param [cause] - The root cause of this [`ListItemNotFoundError`](https://serenity-js.org/api/core/class/ListItemNotFoundError/), if any
      */
     constructor(message: string, cause?: Error) {
         super(ListItemNotFoundError, message, cause);

package/src/errors/model/LogicError.ts

@@ -4,7 +4,7 @@ import { ErrorSerialiser } from '../ErrorSerialiser';
 import { RuntimeError } from './RuntimeError';
 
 /**
- * Thrown to indicate that an {@apilink Interaction}, a {@apilink Task} or a test scenario
+ * Thrown to indicate that an [`Interaction`](https://serenity-js.org/api/core/class/Interaction/), a [`Task`](https://serenity-js.org/api/core/class/Task/) or a test scenario
  * can't be executed due to a logical error.
  *
  * For example, it's not possible to assert on the last HTTP Response if the request
@@ -27,7 +27,7 @@ export class LogicError extends RuntimeError {
 
     /**
      * @param message - Human-readable description of the error
-     * @param [cause] - The root cause of this {@apilink RuntimeError}, if any
+     * @param [cause] - The root cause of this [`RuntimeError`](https://serenity-js.org/api/core/class/RuntimeError/), if any
      */
     constructor(message: string, cause?: Error) {
         super(LogicError, message, cause);

package/src/errors/model/OperationInterruptedError.ts

@@ -4,7 +4,7 @@ import { ErrorSerialiser } from '../ErrorSerialiser';
 import { RuntimeError } from './RuntimeError';
 
 /**
- * Thrown to indicate that a {@apilink Scheduler|scheduled operation}
+ * Thrown to indicate that a [scheduled operation](https://serenity-js.org/api/core/class/Scheduler/)
  * has been stopped before it was completed.
  *
  * @group Errors
@@ -27,7 +27,7 @@ export class OperationInterruptedError extends RuntimeError {
      *  Human-readable description of the error
      *
      * @param [cause]
-     *  The root cause of this {@apilink RuntimeError}, if any
+     *  The root cause of this [`RuntimeError`](https://serenity-js.org/api/core/class/RuntimeError/), if any
      */
     constructor(
         message: string,

package/src/errors/model/RuntimeError.ts

@@ -36,7 +36,7 @@ import { TinyType } from 'tiny-types';
  *   })
  * ```
  *
- * ## Registering a custom error with {@apilink ErrorSerialiser}
+ * ## Registering a custom error with [`ErrorSerialiser`](https://serenity-js.org/api/core/class/ErrorSerialiser/)
  *
  * ```ts
  * import { RuntimeError } from '@serenity-js/core'
@@ -70,7 +70,7 @@ export abstract class RuntimeError extends Error {
     /**
      * @param type - Constructor function used to instantiate a subclass of a RuntimeError
      * @param message - Human-readable description of the error
-     * @param [cause] - The root cause of this {@apilink RuntimeError}, if any
+     * @param [cause] - The root cause of this [`RuntimeError`](https://serenity-js.org/api/core/class/RuntimeError/), if any
      */
     protected constructor(
         type: new (...args: any[]) => RuntimeError,

package/src/errors/model/TestCompromisedError.ts

@@ -38,7 +38,7 @@ export class TestCompromisedError extends RuntimeError {
 
     /**
      * @param message - Human-readable description of the error
-     * @param [cause] - The root cause of this {@apilink RuntimeError}, if any
+     * @param [cause] - The root cause of this [`RuntimeError`](https://serenity-js.org/api/core/class/RuntimeError/), if any
      */
     constructor(message: string, cause?: Error) {
         super(TestCompromisedError, message, cause);

package/src/errors/model/TimeoutExpiredError.ts

@@ -4,7 +4,7 @@ import { ErrorSerialiser } from '../ErrorSerialiser';
 import { RuntimeError } from './RuntimeError';
 
 /**
- * Thrown to indicate that an {@apilink Interaction}, a {@apilink Task} or a test scenario
+ * Thrown to indicate that an [`Interaction`](https://serenity-js.org/api/core/class/Interaction/), a [`Task`](https://serenity-js.org/api/core/class/Task/) or a test scenario
  * took longer to execute than the expected timeout.
  *
  * @group Errors
@@ -27,7 +27,7 @@ export class TimeoutExpiredError extends RuntimeError {
      *  Human-readable description of the error
      *
      * @param [cause]
-     *  The root cause of this {@apilink RuntimeError}, if any
+     *  The root cause of this [`RuntimeError`](https://serenity-js.org/api/core/class/RuntimeError/), if any
      */
     constructor(
         message: string,

package/src/errors/model/UnknownError.ts

@@ -23,7 +23,7 @@ export class UnknownError extends RuntimeError {
 
     /**
      * @param message - Human-readable description of the error
-     * @param [cause] - The root cause of this {@apilink RuntimeError}, if any
+     * @param [cause] - The root cause of this [`RuntimeError`](https://serenity-js.org/api/core/class/RuntimeError/), if any
      */
     constructor(message: string, cause?: Error) {
         super(UnknownError, message, cause);

package/src/events/ActivityFinished.ts

@@ -5,7 +5,7 @@ import type { Timestamp } from '../screenplay';
 import { DomainEvent } from './DomainEvent';
 
 /**
- * Emitted when an {@apilink Activity} is finished.
+ * Emitted when an [`Activity`](https://serenity-js.org/api/core/class/Activity/) is finished.
  *
  * @group Events
  */

package/src/events/ActivityStarts.ts

@@ -5,7 +5,7 @@ import type { Timestamp } from '../screenplay';
 import { DomainEvent } from './DomainEvent';
 
 /**
- * Emitted when an {@apilink Activity} starts.
+ * Emitted when an [`Activity`](https://serenity-js.org/api/core/class/Activity/) starts.
  *
  * @group Events
  */

package/src/events/BusinessRuleDetected.ts

@@ -6,7 +6,7 @@ import { Timestamp } from '../screenplay';
 import { DomainEvent } from './DomainEvent';
 
 /**
- * Emitted by [@serenity-js/cucumber](/api/cucumber)
+ * Emitted by [@serenity-js/cucumber](https://serenity-js.org/api/cucumber)
  * when a [business rule](https://cucumber.io/docs/gherkin/reference/#rule) is detected.
  *
  * @group Events

package/src/events/SceneFinishes.ts

@@ -7,7 +7,8 @@ import { DomainEvent } from './DomainEvent';
 
 /**
  * Emitted by a Serenity/JS test runner adapter, right before a test and all its associated test hooks finish.
- * Triggers any clean-up operations that might be required, such as discarding of the {@apilink Discardable} abilities.
+ * Triggers any clean-up operations that might be required, such as discarding of
+ * the [discardable](https://serenity-js.org/api/core/interface/Discardable/) abilities.
  *
  * @group Events
  */

package/src/instance.ts

@@ -19,10 +19,10 @@ export const serenity = new Serenity(clock);
  * so this function should be called exactly once
  * in your test suite.
  *
- * This function is an alias for {@apilink Serenity.configure}.
+ * This function is an alias for [`Serenity.configure`](https://serenity-js.org/api/core/class/Serenity/#configure).
  *
  * :::tip configure vs engage
-  * If you want to retain the configuration but reset the {@apilink Cast|cast of actors}, use {@apilink engage} instead.
+  * If you want to retain the configuration but reset the [cast of actors](https://serenity-js.org/api/core/class/Cast/), use [`engage`](https://serenity-js.org/api/core/function/engage/) instead.
  * :::
  *
  * @param config
@@ -34,26 +34,26 @@ export function configure(config: SerenityConfig): void {
 }
 
 /**
- * Re-configures Serenity/JS with a new {@apilink Cast} of {@apilink Actor|actors}
- * you want to use in any subsequent calls to {@apilink actorCalled}.
+ * Re-configures Serenity/JS with a new [cast](https://serenity-js.org/api/core/class/Cast/) of [actors](https://serenity-js.org/api/core/class/Actor/)
+ * you want to use in any subsequent calls to [`actorCalled`](https://serenity-js.org/api/core/function/actorCalled/).
  *
- * This function is an alias for {@apilink Serenity.engage},
- * which provides an alternative to calling {@apilink Actor.whoCan} directly in your tests
+ * This function is an alias for [`Serenity.engage`](https://serenity-js.org/api/core/class/Serenity/#engage),
+ * which provides an alternative to calling [`Actor.whoCan`](https://serenity-js.org/api/core/class/Actor/#whoCan) directly in your tests
  * and is typically invoked in a "before all" or "before each" hook of your test runner of choice.
  *
  * :::tip configure vs engage
- * Calling {@apilink engage} replaces the currently configured {@apilink Cast|cast of actors},
+ * Calling [`engage`](https://serenity-js.org/api/core/function/engage/) replaces the currently configured [cast of actors](https://serenity-js.org/api/core/class/Cast/),
  * but doesn't affect any other configuration.
- * If you want to reset the Serenity/JS configuration completely, use {@apilink configure} instead.
+ * If you want to reset the Serenity/JS configuration completely, use [`configure`](https://serenity-js.org/api/core/function/configure/) instead.
  * :::
  *
- * If your implementation of the {@apilink Cast} interface is stateless,
+ * If your implementation of the [cast](https://serenity-js.org/api/core/class/Cast/) interface is stateless,
  * you can invoke this function just once before your entire test suite is executed, see
  * - [`beforeAll`](https://jasmine.github.io/api/3.6/global.html#beforeAll) in Jasmine,
  * - [`before`](https://mochajs.org/#hooks) in Mocha,
  * - [`BeforeAll`](https://github.com/cucumber/cucumber-js/blob/master/docs/support_files/hooks.md#beforeall--afterall) in Cucumber.js
  *
- * However, if your {@apilink Cast} holds state that you want to reset before each scenario,
+ * However, if your [cast](https://serenity-js.org/api/core/class/Cast/) holds state that you want to reset before each scenario,
  * it's better to invoke `engage` before each test using:
  * - [`beforeEach`](https://jasmine.github.io/api/3.6/global.html#beforeEach) in Jasmine
  * - [`beforeEach`](https://mochajs.org/#hooks) in Mocha,
@@ -116,8 +116,8 @@ export function configure(config: SerenityConfig): void {
  *
  * ### Using with Playwright Test runner
  *
- * [Serenity/JS Playwright Test module](/api/playwright-test) will configure the cast on your behalf,
- * so you don't need to call {@apilink engage}.
+ * [Serenity/JS Playwright Test module](https://serenity-js.org/api/playwright-test) will configure the cast on your behalf,
+ * so you don't need to call [`engage`](https://serenity-js.org/api/core/function/engage/).
  *
  * ```ts
  * import { describe, it, test } from '@serenity-js/playwright-test'
@@ -134,9 +134,9 @@ export function configure(config: SerenityConfig): void {
  * ```
  *
  * ## Learn more
- * - {@apilink Actor}
- * - {@apilink Cast}
- * - {@apilink Serenity.engage}
+ * - [`Actor`](https://serenity-js.org/api/core/class/Actor/)
+ * - [`Cast`](https://serenity-js.org/api/core/class/Cast/)
+ * - [`Serenity.engage`](https://serenity-js.org/api/core/class/Serenity/#engage)
  *
  * @param actors
  *
@@ -147,10 +147,10 @@ export function engage(actors: Cast): void {
 }
 
 /**
- * Instantiates or retrieves an {@apilink Actor}
+ * Instantiates or retrieves an [`Actor`](https://serenity-js.org/api/core/class/Actor/)
  * called `name` if one has already been instantiated.
  *
- * This method is an alias for {@apilink Serenity.theActorCalled}.
+ * This method is an alias for [`Serenity.theActorCalled`](https://serenity-js.org/api/core/class/Serenity/#theActorCalled).
  *
  * ## Usage with Cucumber
  *
@@ -199,9 +199,9 @@ export function engage(actors: Cast): void {
  *
  * ## Usage with Playwright Test
  *
- * When using [Serenity/JS with Playwright Test](/api/playwright-test/), you should use either
- * the default [`actor`](/api/playwright-test/interface/SerenityFixtures/#actorCalled) fixture
- * or the injected [`actorCalled`](/api/playwright-test/interface/SerenityFixtures/#actorCalled) function
+ * When using [Serenity/JS with Playwright Test](https://serenity-js.org/api/playwright-test/), you should use either
+ * the default [`actor`](https://serenity-js.org/api/playwright-test/interface/SerenityFixtures/#actorCalled) fixture
+ * or the injected [`actorCalled`](https://serenity-js.org/api/playwright-test/interface/SerenityFixtures/#actorCalled) function
  * instead of importing it from `@serenity-js/core`.
  *
  * ```typescript
@@ -219,10 +219,10 @@ export function engage(actors: Cast): void {
  *
  * ## Learn more
  *
- * - {@apilink engage}
- * - {@apilink Actor}
- * - {@apilink Cast}
- * - {@apilink Serenity.theActorCalled}
+ * - [`engage`](https://serenity-js.org/api/core/function/engage/)
+ * - [`Actor`](https://serenity-js.org/api/core/class/Actor/)
+ * - [`Cast`](https://serenity-js.org/api/core/class/Cast/)
+ * - [`Serenity.theActorCalled`](https://serenity-js.org/api/core/class/Serenity/#theActorCalled)
  *
  * @param name
  *  The name of the actor to instantiate or retrieve
@@ -235,11 +235,11 @@ export function actorCalled(name: string): Actor {
 
 /**
  * Retrieves an actor who was last instantiated or retrieved
- * using {@apilink actorCalled}.
+ * using [`actorCalled`](https://serenity-js.org/api/core/function/actorCalled/).
  *
  * This function is particularly useful when automating Cucumber scenarios.
  *
- * This function is an alias for {@apilink Serenity.theActorInTheSpotlight}.
+ * This function is an alias for [`Serenity.theActorInTheSpotlight`](https://serenity-js.org/api/core/class/Serenity/#theActorInTheSpotlight).
  *
  * ## Usage with Cucumber
  *
@@ -260,10 +260,10 @@ export function actorCalled(name: string): Actor {
  *
  * ## Learn more
  *
- * - {@apilink engage}
- * - {@apilink actorCalled}
- * - {@apilink Actor}
- * - {@apilink Cast}
+ * - [`engage`](https://serenity-js.org/api/core/function/engage/)
+ * - [`actorCalled`](https://serenity-js.org/api/core/function/actorCalled/)
+ * - [`Actor`](https://serenity-js.org/api/core/class/Actor/)
+ * - [`Cast`](https://serenity-js.org/api/core/class/Cast/)
  *
  * @group Actors
  */

package/src/io/format.ts

@@ -2,14 +2,23 @@ import type { Answerable } from '../screenplay';
 import { stringified } from './stringified';
 
 /**
- * {@apilink format} is a factory function returning
+ * `format` is a factory function returning
  * a [tag function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#Tagged_template_literals)
- * that produces a human-readable description of a template containing
- * one or more {@apilink Answerable|Answerables}.
+ * that produces a human-readable `string` description of a template containing
+ * one or more [answerables](https://serenity-js.org/api/core/#Answerable).
  *
- * Typically, you'll want to use {@apilink d} and {@apilink f} shorthands instead:
- * - the {@apilink d} function works best for generating a **description** of a parameterised {@apilink Activity}
- * - the {@apilink f} function is better suited for debugging.
+ * Typically, you'll want to use `d` and `f` shorthands instead, or the modern alternative - `the`:
+ * - the [`d`](https://serenity-js.org/api/core/function/d/) function works best for generating a **static description** of a parameterised [`Activity`](https://serenity-js.org/api/core/class/Activity/)
+ * - the [`f`](https://serenity-js.org/api/core/function/f/) function is better suited for debugging
+ * - the [`the`](https://serenity-js.org/api/core/function/f/) function works best for generating a **dynamic description** of a parameterised [`Activity`](https://serenity-js.org/api/core/class/Activity/)
+ *
+ * :::tip Use `the` instead of `format`
+ * `format`, `d` and `f` are the original Serenity/JS string formatting functions,
+ * still present in the framework for backwards compatibility purposes.
+ *
+ * To generate a dynamic description of a `Question` or `Interaction`,
+ * use [`the`](https://serenity-js.org/api/core/function/the/) function instead.
+ * :::
  *
  * ## Using `format`
  *

package/src/io/loader/ModuleLoader.ts

@@ -78,7 +78,7 @@ export class ModuleLoader {
     }
 
     /**
-     * Returns {@apilink Version} of module specified by `moduleId`, based on its `package.json`.
+     * Returns `Version` of module specified by `moduleId`, based on its `package.json`.
      *
      * @param moduleId
      */

package/src/io/reflection/ValueInspector.ts

@@ -11,7 +11,7 @@ export class ValueInspector {
     }
 
     /**
-     * Checks if the value is a named {@apilink Function}
+     * Checks if the value is a named [`Function`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function)
      *
      * @param value
      */
@@ -115,8 +115,8 @@ export class ValueInspector {
     static isNative(value: unknown): value is Function {  // eslint-disable-line @typescript-eslint/ban-types
 
         const
-            toString = Object.prototype.toString,    // Used to resolve the internal `{@apilink Class}` of values
-            fnToString = Function.prototype.toString,  // Used to resolve the decompiled source of functions
+            toString = Object.prototype.toString,           // Used to resolve the internal `Class` of values
+            fnToString = Function.prototype.toString,       // Used to resolve the decompiled source of functions
             hostConstructor = /^\[object .+?Constructor]$/; // Used to detect host constructors (Safari > 4; really typed array specific)
 
         // Compile a regexp using a common native method as a template.

package/src/io/stringified.ts

@@ -13,7 +13,7 @@ interface StringifyConfig {
 }
 
 /**
- * Provides a human-readable description of the {@apilink Answerable<T>}.
+ * Provides a human-readable description of the [`Answerable<T>`](https://serenity-js.org/api/core/#Answerable).
  * Similar to [Node util~inspect](https://nodejs.org/api/util.html#utilinspectobject-options).
  *
  * @param value

package/src/io/trimmed.ts

@@ -1,7 +1,7 @@
 /**
  * A tag function trimming the leading and trailing whitespace from multi-line strings.
  *
- * @apilink https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#Tagged_template_literals
+ * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Template_literals#Tagged_template_literals
  *
  * @param templates
  * @param placeholders