@serenity-js/core 3.0.0-rc.8 → 3.0.0

package/src/screenplay/questions/AnswersQuestions.ts

@@ -0,0 +1,20 @@
+import { Answerable } from '../Answerable';
+
+/**
+ * Describes an {@apilink Actor} who can answer a {@apilink Question} about the system under test.
+ *
+ * ## Learn more
+ *
+ * - {@apilink Question}
+ * - {@apilink Actor}
+ *
+ * @group Actors
+ */
+export interface AnswersQuestions {
+
+    /**
+     * Makes the {@apilink Actor} evaluate an {@apilink Answerable}
+     * and return the value it holds.
+     */
+    answer<T>(answerable: Answerable<T>): Promise<T>;
+}

package/src/screenplay/questions/Check.ts

@@ -1,90 +1,79 @@
 import { d } from '../../io';
+import { PerformsActivities } from '../activities';
 import { Activity } from '../Activity';
-import { AnswersQuestions, PerformsActivities } from '../actor';
 import { Answerable } from '../Answerable';
+import { AnswersQuestions } from '../questions';
 import { Task } from '../Task';
 import { Expectation } from './Expectation';
 import { ExpectationMet } from './expectations';
 
 /**
- * @desc
- *  A control flow statement that enables the {@link @serenity-js/core/lib/screenplay/actor~Actor}
- *  either to choose whether or not to perform a series of activities,
- *  or to choose which of the two provided series of activities to perform.
+ * A [flow control statement](https://en.wikipedia.org/wiki/Control_flow)
+ * that enables an {@apilink Actor} to decide between two alternate series of {@apilink Activity|activities}.
  *
- * @example <caption>Choose from two alternatives</caption>
- *  import { equals } from '@serenity-js/assertions';
- *  import { Check } from '@serenity-js/core';
+ * Think of it as a Screenplay Pattern equivalent of the traditional `if` statement.
  *
- *  actor.attemptsTo(
- *      Check.whether(process.env.MODE, equals('prod'))
- *          .andIfSo(
- *              LogInAsProdUser(),
- *          )
- *          .otherwise(
- *              LogInAsTestUser(),
- *          )
- *  );
+ * ## Choose between two alternative sequences of activities
  *
- * @example <caption>Choose whether or not to perform an activity</caption>
- *  import { equals } from '@serenity-js/assertions';
- *  import { Check } from '@serenity-js/core';
- *  import { isDisplayed } from '@serenity-js/protractor';
+ * ```ts
+ * import { equals } from '@serenity-js/assertions'
+ * import { actorCalled, Check } from '@serenity-js/core'
  *
- *  actor.attemptsTo(
- *      Check.whether(NewsletterModal(), isDisplayed())
- *          .andIfSo(
- *              DismissModal(),
- *          )
- *  );
+ * await actorCalled('Chuck').attemptsTo(
+ *   Check.whether(process.env.MODE, equals('prod'))
+ *     .andIfSo(
+ *       LogInAsProdUser(),
+ *     )
+ *     .otherwise(
+ *       LogInAsTestUser(),
+ *     )
+ * )
+ * ```
  *
- * @extends {@serenity-js/core/lib/screenplay~Task}
+ * ## Perform a sequence of activities when a condition is met
  *
- * @see https://en.wikipedia.org/wiki/Control_flow
+ * ```ts
+ * import { actorCalled, Check } from '@serenity-js/core'
+ * import { isVisible } from '@serenity-js/web'
+ *
+ * await actorCalled('Chuck').attemptsTo(
+ *   Check.whether(CookieConsentBanner(), isVisible())
+ *     .andIfSo(
+ *         AcceptNecessaryCookies(),
+ *     )
+ * )
+ * ```
+ *
+ * @group Activities
  */
 export class Check<Actual> extends Task {
     // eslint-disable-next-line @typescript-eslint/explicit-module-boundary-types
-    static whether<A>(actual: Answerable<A>, expectation: Expectation<A>) {
+    static whether<Actual_Type>(actual: Answerable<Actual_Type>, expectation: Expectation<Actual_Type>): { andIfSo: (...activities: Activity[]) => Check<Actual_Type> } {
         return {
-            andIfSo: (...activities: Activity[]) => new Check(actual, expectation, activities),
+            andIfSo: (...activities: Activity[]) =>
+                new Check(actual, expectation, activities),
         };
     }
 
-    /**
-     *
-     * @param actual
-     * @param expectation
-     * @param activities
-     * @param alternativeActivities
-     */
-    constructor(
+    protected constructor(
         private readonly actual: Answerable<Actual>,
         private readonly expectation: Expectation<Actual>,
         private readonly activities: Activity[],
         private readonly alternativeActivities: Activity[] = [],
     ) {
-        super();
+        super(d`#actor checks whether ${ actual } does ${ expectation }`);
     }
 
     /**
-     * @param {...@serenity-js/core/lib/screenplay~Activity[]} alternativeActivities
-     * @return {@serenity-js/core/lib/screenplay~Task}
+     * @param alternativeActivities
+     *  A sequence of {@apilink Activity|activities} to perform when the {@apilink Expectation} is not met.
      */
     otherwise(...alternativeActivities: Activity[]): Task {
         return new Check<Actual>(this.actual, this.expectation, this.activities, alternativeActivities);
     }
 
     /**
-     * @desc
-     *  Makes the provided {@link @serenity-js/core/lib/screenplay/actor~Actor}
-     *  perform this {@link @serenity-js/core/lib/screenplay~Task}.
-     *
-     * @param {AnswersQuestions & PerformsActivities} actor
-     * @returns {Promise<void>}
-     *
-     * @see {@link @serenity-js/core/lib/screenplay/actor~Actor}
-     * @see {@link @serenity-js/core/lib/screenplay/actor~AnswersQuestions}
-     * @see {@link @serenity-js/core/lib/screenplay/actor~PerformsActivities}
+     * @inheritDoc
      */
     async performAs(actor: AnswersQuestions & PerformsActivities): Promise<void> {
         const outcome = await actor.answer(this.expectation.isMetFor(this.actual));
@@ -93,14 +82,4 @@ export class Check<Actual> extends Task {
             ? actor.attemptsTo(...this.activities)
             : actor.attemptsTo(...this.alternativeActivities);
     }
-
-    /**
-     * @desc
-     *  Generates a description to be used when reporting this {@link @serenity-js/core/lib/screenplay~Activity}.
-     *
-     * @returns {string}
-     */
-    toString(): string {
-        return d`#actor checks whether ${ this.actual } does ${ this.expectation }`;
-    }
 }

package/src/screenplay/questions/Expectation.ts

@@ -1,65 +1,193 @@
-import { d } from '../../io';
-import { Answerable, AnswersQuestions, ExpectationMet, ExpectationNotMet, Question, QuestionAdapter } from '../';
+import { JSONValue } from 'tiny-types';
+
+import { asyncMap, d } from '../../io';
+import { Answerable, AnswersQuestions, ExpectationDetails, ExpectationMet, ExpectationNotMet, Question, QuestionAdapter } from '../';
 import { ExpectationOutcome } from './expectations';
 
 /**
- * @public
- *
- * @typedef {function(actual: Answerable<Actual>) => Promise<ExpectationOutcome<Expected, Actual>> | ExpectationOutcome<unknown, Actual>} Predicate<Actual>
+ * @group Expectations
  */
 export type Predicate<Actual> = (actor: AnswersQuestions, actual: Answerable<Actual>) =>
-    Promise<ExpectationOutcome<unknown, Actual>> | ExpectationOutcome<unknown, Actual>;     // eslint-disable-line @typescript-eslint/indent
+    Promise<ExpectationOutcome> | ExpectationOutcome;     // eslint-disable-line @typescript-eslint/indent
 
+type AnswerableArguments<Arguments extends Array<unknown>> = { [Index in keyof Arguments]: Answerable<Arguments[Index]> };
 
 /**
- * @desc
- *  Defines an expectation to be used with [assertions](/modules/assertions)
- *  and {@link Question}s like {@link List}.
+ * Defines an expectation to be used with {@apilink @apilink Wait.until}, {@apilink Check.whether}, {@apilink Ensure.that}
+ * and as part of the Page Element Query Language with {@apilink PageElements.where} and {@apilink List.where}.
  *
- * @extends {Question}
+ * @group Expectations
  */
 export class Expectation<Actual> {
 
     /**
-     * @desc
-     *  Used to define a simple {@link Expectation}
+     * A factory method to that makes defining custom {@apilink Expectation|expectations} easier
+     *
+     * #### Defining a custom expectation
+     *
+     * ```ts
+     * import { Expectation } from '@serenity-js/core'
+     * import { PageElement } from '@serenity-js/web'
+     *
+     * const isEmpty = Expectation.define(
+     *   'isEmpty',         // name of the expectation function to be used when producing an AssertionError
+     *   'become empty',    // human-readable description of the relationship between expected and actual values
+     *   async (actual: PageElement) => {
+     *     const value = await actual.value();
+     *     return value.length === 0;
+     *   }
+     * )
+     * ```
+     *
+     * #### Using a custom expectation in an assertion
+     *
+     * ```ts
+     * import { Ensure } from '@serenity-js/assertions'
+     * import { actorCalled } from '@serenity-js/core'
+     * import { By, Clear, PageElement } from '@serenity-js/web'
+     *
+     * const nameField = () =>
+     *   PageElement.located(By.css('[data-test-id="name"]')).describedAs('name field');
+     *
+     * await actorCalled('Izzy').attemptsTo(
+     *   Clear.the(nameField()),
+     *   Ensure.that(nameField(), isEmpty())
+     * )
+     * ```
+     *
+     * #### Using a custom expectation in a control flow statement
+     *
+     * ```ts
+     * import { not } from '@serenity-js/assertions'
+     * import { actorCalled, Check, Duration, Wait } from '@serenity-js/core'
+     * import { By, PageElement } from '@serenity-js/web'
+     *
+     * const nameField = () =>
+     *   PageElement.located(By.css('[data-test-id="name"]')).describedAs('name field');
      *
-     * @example
-     *  import { actorCalled, Expectation } from '@serenity-js/core';
-     *  import { Ensure } from '@serenity-js/assertions';
+     * await actorCalled('Izzy').attemptsTo(
+     *   Check.whether(nameField(), isEmpty())
+     *     .andIfSo(
+     *       Enter.theValue(actorInTheSpotlight().name).into(nameField()),
+     *     ),
+     * )
+     * ```
+     *
+     * #### Using a custom expectation in a synchronisation statement
+     *
+     * ```ts
+     * import { not } from '@serenity-js/assertions'
+     * import { actorCalled, Duration, Wait } from '@serenity-js/core'
+     * import { By, PageElement } from '@serenity-js/web'
+     *
+     * const nameField = () =>
+     *   PageElement.located(By.css('[data-test-id="name"]')).describedAs('name field');
+     *
+     * await actorCalled('Izzy').attemptsTo(
+     *   Enter.theValue(actorInTheSpotlight().name).into(nameField()),
+     *
+     *   Wait.upTo(Duration.ofSeconds(2))
+     *     .until(nameField(), not(isEmpty())),
+     * )
+     * ```
+     *
+     * #### Learn more
+     * - {@apilink Ensure}
+     * - {@apilink Check}
+     * - {@apilink Wait}
+     *
+     * @param functionName
+     *  Name of the expectation function to be used when producing an {@apilink AssertionError}
+     *
+     * @param relationship
+     *  Human-readable description of the relationship between the `expected` and the `actual` values.
+     *  Used when reporting {@apilink Activity|activities} performed by an {@apilink Actor|actor}
+     *
+     * @param predicate
+     */
+    static define<Actual_Type, PredicateArguments extends Array<unknown>>(
+        functionName: string,
+        relationship: ((...answerableArguments: AnswerableArguments<PredicateArguments>) => string) | string,
+        predicate: (actual: Actual_Type, ...predicateArguments: PredicateArguments) => Promise<boolean> | boolean,
+    ): (...answerableArguments: AnswerableArguments<PredicateArguments>) => Expectation<Actual_Type>
+    {
+        return Object.defineProperty(function(...answerableArguments: AnswerableArguments<PredicateArguments>): Expectation<Actual_Type> {
+            const description = typeof relationship === 'function' ? relationship(...answerableArguments)
+                : (answerableArguments.length === 1 ? relationship.trim() + d` ${answerableArguments[0]}`
+                    : relationship);
+
+            return new Expectation<Actual_Type>(
+                functionName,
+                description,
+                async (actor: AnswersQuestions, actualValue: Answerable<Actual_Type>): Promise<ExpectationOutcome> => {
+                    const predicateArguments = await asyncMap(answerableArguments, answerableArgument =>
+                        actor.answer(answerableArgument as Answerable<JSONValue>)
+                    );
+
+                    const actual    = await actor.answer(actualValue);
+
+                    const result    = await predicate(actual, ...predicateArguments as PredicateArguments);
+
+                    const expectationDetails = ExpectationDetails.of(functionName, ...predicateArguments);
+
+                    const expected = predicateArguments.length > 0
+                        ? predicateArguments[0]
+                        : true;     // the only parameter-less expectations are boolean ones like `isPresent`, `isActive`, etc.
+
+                    return result
+                        ? new ExpectationMet(description, expectationDetails, expected, actual)
+                        : new ExpectationNotMet(description, expectationDetails, expected, actual);
+                }
+            )
+        }, 'name', {value: functionName, writable: false});
+    }
+
+    /**
+     * Used to define a simple {@apilink Expectation}
+     *
+     * #### Simple parameterised expectation
+     *
+     * ```ts
+     *  import { actorCalled, Expectation } from '@serenity-js/core'
+     *  import { Ensure } from '@serenity-js/assertions'
      *
      *  function isDivisibleBy(expected: Answerable<number>): Expectation<number> {
      *      return Expectation.thatActualShould<number, number>('have value divisible by', expected)
      *          .soThat((actualValue, expectedValue) => actualValue % expectedValue === 0);
      *  }
      *
-     *  actorCalled('Erica').attemptsTo(
+     *  await actorCalled('Erica').attemptsTo(
      *      Ensure.that(4, isDivisibleBy(2)),
-     *  );
+     *  )
+     * ```
      *
-     * @param {string} relationshipName
-     * @param {@serenity-js/core/lib/screenplay~Answerable<E>} expectedValue
+     * @param relationshipName
+     *  Name of the relationship between the `actual` and the `expected`. Use format `have value <adjective>`
+     *  so that the description works in both positive and negative contexts, e.g. `Waited until 5 does have value greater than 2`,
+     *  `Expected 5 to not have value greater than 2`.
      *
-     * @returns {"soThat": function(predicate: Predicate<Expected, Actual>): Expectation<Expected, Actual>}
+     * @param expectedValue
      */
-    static thatActualShould<E, A>(relationshipName: string, expectedValue?: Answerable<E>): {
-        soThat: (simplifiedPredicate: (actualValue: A, expectedValue: E) => Promise<boolean> | boolean) => Expectation<A>,
+    static thatActualShould<Expected_Type, Actual_Type>(relationshipName: string, expectedValue?: Answerable<Expected_Type>): {
+        soThat: (simplifiedPredicate: (actualValue: Actual_Type, expectedValue: Expected_Type) => Promise<boolean> | boolean) => Expectation<Actual_Type>,
     } {
         return ({
-            soThat: (simplifiedPredicate: (actualValue: A, expectedValue: E) => Promise<boolean> | boolean): Expectation<A> => {
-                const subject = relationshipName + ' ' + d`${expectedValue}`;
+            soThat: (simplifiedPredicate: (actualValue: Actual_Type, expectedValue: Expected_Type) => Promise<boolean> | boolean): Expectation<Actual_Type> => {
+                const message = relationshipName + ' ' + d`${expectedValue}`;
 
-                return new Expectation<A>(
-                    subject,
-                    async (actor: AnswersQuestions, actualValue: Answerable<A>): Promise<ExpectationOutcome<E, A>> => {
-                        const expected = await actor.answer(expectedValue);
-                        const actual   = await actor.answer(actualValue);
+                return new Expectation<Actual_Type>(
+                    'unknown',
+                    message,
+                    async (actor: AnswersQuestions, actualValue: Answerable<Actual_Type>): Promise<ExpectationOutcome> => {
+                        const expected  = await actor.answer(expectedValue);
+                        const actual    = await actor.answer(actualValue);
 
-                        const result   = await simplifiedPredicate(actual, expected);
+                        const result    = await simplifiedPredicate(actual, expected);
+                        const expectationDetails = ExpectationDetails.of('unknown');
 
                         return result
-                            ? new ExpectationMet(subject, expected, actual)
-                            : new ExpectationNotMet(subject, expected, actual);
+                            ? new ExpectationMet(message, expectationDetails, expected, actual)
+                            : new ExpectationNotMet(message, expectationDetails, expected, actual);
                     }
                 );
             },
@@ -67,41 +195,45 @@ export class Expectation<Actual> {
     }
 
     /**
-     * @desc
-     *  Used to compose {@link Expectation}s.
-     *
-     * @example
-     *  import { actorCalled, Expectation } from '@serenity-js/core';
-     *  import { Ensure, and, or, isGreaterThan, isLessThan, equals  } from '@serenity-js/assertions';
-     *
-     *  function isWithin(lowerBound: number, upperBound: number) {
-     *      return Expectation
-     *          .to(`have value within ${ lowerBound } and ${ upperBound }`)
-     *          .soThatActual(and(
-     *              or(isGreaterThan(lowerBound), equals(lowerBound)),
-     *              or(isLessThan(upperBound), equals(upperBound)),
-     *          ));
+     * Used to compose {@apilink Expectation|expectations}.
+     *
+     * #### Composing {@apilink Expectation|expectations}
+     *
+     * ```ts
+     * import { actorCalled, Expectation } from '@serenity-js/core'
+     * import { Ensure, and, or, isGreaterThan, isLessThan, equals  } from '@serenity-js/assertions'
+     *
+     * function isWithin(lowerBound: number, upperBound: number) {
+     *   return Expectation
+     *     .to(`have value within ${ lowerBound } and ${ upperBound }`)
+     *     .soThatActual(
+     *       and(
+     *         or(isGreaterThan(lowerBound), equals(lowerBound)),
+     *         or(isLessThan(upperBound), equals(upperBound)),
+     *       )
+     *     )
      *  }
      *
-     *  actorCalled('Erica').attemptsTo(
+     *  await actorCalled('Erica').attemptsTo(
      *      Ensure.that(5, isWithin(3, 6)),
-     *  );
-     *
-     * @param {string} relationshipName
+     *  )
+     * ```
      *
-     * @returns {"soThat": function(...expectations: Array<Expectation<any, A>>): Expectation<any, A>}
+     * @param relationshipName
+     *  Name of the relationship between the `actual` and the `expected`. Use format `have value <adjective>`
+     *  so that the description works in both positive and negative contexts, e.g. `Waited until 5 does have value greater than 2`,
+     *  `Expected 5 to not have value greater than 2`.
      */
-    static to<E, A>(relationshipName: string): {
-        soThatActual: (...expectations: Array<Expectation<A>>) => Expectation<A>,
+    static to<Actual_Type>(relationshipName: string): {
+        soThatActual: (expectation: Expectation<Actual_Type>) => Expectation<Actual_Type>,
     } {
         return {
-            soThatActual: (expectation: Expectation<A>): Expectation<A> => {
-                return new Expectation<A>(
+            soThatActual: (expectation: Expectation<Actual_Type>): Expectation<Actual_Type> => {
+                return new Expectation<Actual_Type>(
+                    'unknown',
                     relationshipName,
-                    async (actor: AnswersQuestions, actualValue: Answerable<A>): Promise<ExpectationOutcome<E, A>> => {
-                        const outcome  = await actor.answer(expectation.isMetFor(actualValue));
-
-                        return outcome as ExpectationOutcome<E, A>;
+                    async (actor: AnswersQuestions, actualValue: Answerable<Actual_Type>): Promise<ExpectationOutcome> => {
+                        return await actor.answer(expectation.isMetFor(actualValue));
                     }
                 );
             },
@@ -109,21 +241,35 @@ export class Expectation<Actual> {
     }
 
     protected constructor(
-        private subject: string,
-        private readonly predicate: Predicate<Actual>,
+        private readonly functionName: string,
+        private description: string,
+        private readonly predicate: Predicate<Actual>
     ) {
     }
 
-    isMetFor(actual: Answerable<Actual>): QuestionAdapter<ExpectationOutcome<unknown, Actual>> {
-        return Question.about(this.subject, actor => this.predicate(actor, actual));
+    /**
+     * Returns a {@apilink QuestionAdapter} that resolves to {@apilink ExpectationOutcome}
+     * indicating that the {@apilink ExpectationMet|expectation was met}
+     * or that the {@apilink ExpectationNotMet|expectation was not met}
+     *
+     * @param actual
+     */
+    isMetFor(actual: Answerable<Actual>): QuestionAdapter<ExpectationOutcome> {
+        return Question.about(this.description, actor => this.predicate(actor, actual));
     }
 
+    /**
+     * @inheritDoc
+     */
     describedAs(subject: string): this {
-        this.subject = subject;
+        this.description = subject;
         return this;
     }
 
+    /**
+     * @inheritDoc
+     */
     toString(): string {
-        return this.subject;
+        return this.description;
     }
 }

package/src/screenplay/questions/List.ts

@@ -1,13 +1,21 @@
-import { LogicError } from '../../errors';
+import { ListItemNotFoundError, LogicError } from '../../errors';
 import { d } from '../../io';
-import { Actor, AnswersQuestions, UsesAbilities } from '../actor';
+import { UsesAbilities } from '../abilities';
+import { Actor } from '../Actor';
 import { Answerable } from '../Answerable';
 import { Question, QuestionAdapter } from '../Question';
+import { AnswersQuestions } from '../questions';
 import { Task } from '../Task';
 import { Expectation } from './Expectation';
 import { ExpectationMet } from './expectations';
 import { MetaQuestion } from './MetaQuestion';
 
+/**
+ * Serenity/JS Screenplay Pattern-style wrapper around {@apilink Array}
+ * and array-like structures - see {@apilink PageElements}.
+ *
+ * @group Questions
+ */
 export class List<Item_Type> extends Question<Promise<Item_Type[]>> {
     private subject: string;
 
@@ -55,7 +63,7 @@ export class List<Item_Type> extends Question<Promise<Item_Type[]>> {
             const items = await this.answeredBy(actor);
 
             if (items.length === 0) {
-                throw new LogicError(d`Can't retrieve the first item from a list with 0 items: ${ items }`)
+                throw new ListItemNotFoundError(d`Can't retrieve the first item from a list with 0 items: ${ items }`)
             }
 
             return items[0];
@@ -67,19 +75,19 @@ export class List<Item_Type> extends Question<Promise<Item_Type[]>> {
             const items = await this.answeredBy(actor);
 
             if (items.length === 0) {
-                throw new LogicError(d`Can't retrieve the last item from a list with 0 items: ${ items }`)
+                throw new ListItemNotFoundError(d`Can't retrieve the last item from a list with 0 items: ${ items }`)
             }
 
             return items[items.length - 1];
         });
     }
 
-    get(index: number): QuestionAdapter<Item_Type> {
+    nth(index: number): QuestionAdapter<Item_Type> {
         return Question.about(`the ${ ordinal(index + 1) } of ${ this.subject }`, async actor => {
             const items = await this.answeredBy(actor);
 
             if (index < 0 || items.length <= index) {
-                throw new LogicError(`Can't retrieve the ${ ordinal(index) } item from a list with ${ items.length } items: ` + d`${ items }`)
+                throw new ListItemNotFoundError(`Can't retrieve the ${ ordinal(index) } item from a list with ${ items.length } items: ` + d`${ items }`)
             }
 
             return items[index];
@@ -229,7 +237,7 @@ class ForEachLoop<Item_Type> extends Task {
         private readonly subject: string,
         private readonly fn: (current: CurrentItem<Item_Type>, index: number, items: Array<Item_Type>) => Promise<void> | void,
     ) {
-        super();
+        super(`#actor iterates over ${ subject }`);
     }
 
     async performAs(actor: Actor): Promise<void> {
@@ -239,12 +247,11 @@ class ForEachLoop<Item_Type> extends Task {
             await this.fn({ actor, item }, index, collection);
         }
     }
-
-    toString(): string {
-        return `#actor iterates over ${ this.subject }`;
-    }
 }
 
+/**
+ * @group Questions
+ */
 export interface CurrentItem<Item_Type> {
     item: Item_Type;
     actor: Actor;

package/src/screenplay/questions/MetaQuestion.ts

@@ -2,39 +2,35 @@ import { Answerable } from '../Answerable';
 import { Question } from '../Question';
 
 /**
- * @desc
- *  A {@link Question} about another {@link Answerable}, used to retrieve a transformed version of the value it holds, or to compose {@link Question}s.
+ * A "meta question" is a {@apilink Question} about another {@apilink Answerable},
+ * used to retrieve a transformed version of the value that answerable holds.
  *
- *  For example, the question [`Text.of`](/modules/protractor/class/src/screenplay/questions/text/Text.ts~Text.html)
- *  returns text content of an {@link ElementFinder} returned by [`Target`](/modules/protractor/class/src/screenplay/questions/targets/Target.ts~Target.html),
- *  which is a `Question<ElementFinder>`.
+ * For example, the question {@apilink Text.of}
+ * returns text content of a {@apilink PageElement}.
  *
- *  `MetaQuestion`s are typically used when filtering a {@link List}.
+ * {@apilink MetaQuestion|Meta questions} are typically used when filtering a {@apilink List}.
  *
- * @see {@link List}
+ * ## Learn more
+ * - {@apilink List}
  *
- * @public
- * @interface
+ * @group Questions
  */
 export interface MetaQuestion<Supported_Answerable_Type extends Answerable<any>, Answer> {
+
     /**
-     * @desc
-     *  Transforms a given `answerable`
-     *  to another {@link Question}.
-     *
-     * @type {function<T>(another: Answerable): Question<Answer>}
-     * @public
+     * Transforms a given `answerable` to another {@apilink Question}.
      *
-     * @see {@link List}
+     * #### Learn more
+     * - {@apilink List}
      */
-    of: (answerable: Supported_Answerable_Type) => Question<Answer>;
+    of(answerable: Supported_Answerable_Type): Question<Answer>;
 
     /**
-     * @desc
-     *  Human-readable description of a given {@link MetaQuestion},
+     * Human-readable description of this {@apilink MetaQuestion},
+     * typically involving the description of the subject.
      *
-     * @type {function(): string}
-     * @public
+     * For example, a description of a meta question obout "the text of an element"
+     * would be `text of ${ element.toString() }`
      */
-    toString: () => string;
+    toString(): string;
 }