Consolidate docstring comments for Locations

m-hulbert · m-hulbert · commit 61535dd2e1f9 · 2023-11-23T11:53:25.000Z
diff --git a/src/Locations.ts b/src/Locations.ts
@@ -12,27 +12,57 @@ import SpaceUpdate from './SpaceUpdate.js';
 export namespace LocationsEvents {
   /**
    * The data attached to an {@link LocationsEventMap.update | `update`} event.
+   *
+   * The following is an example payload of a location event:
+   *
+   * ```json
+   * {
+   *   "member": {
+   *     "clientId": "clemons#142",
+   *     "connectionId": "hd9743gjDc",
+   *     "isConnected": true,
+   *     "profileData": {
+   *       "username": "Claire Lemons",
+   *       "avatar": "https://slides-internal.com/users/clemons.png"
+   *     },
+   *     "location": {
+   *       "slide": "3",
+   *       "component": "slide-title"
+   *     },
+   *     "lastEvent": {
+   *       "name": "update",
+   *       "timestamp": 1972395669758
+   *     }
+   *   },
+   *   "previousLocation": {
+   *     "slide": "2",
+   *     "component": null
+   *   },
+   *   "currentLocation": {
+   *     "slide": "3",
+   *     "component": "slide-title"
+   *   }
+   * }
+   * ```
    */
   export interface UpdateEvent {
     /**
      * The member whose location changed.
      */
     member: SpaceMember;
     /**
-     * <!-- MOVED FROM Locations.subscribe -->
      * The new location of the member.
      */
     currentLocation: unknown;
     /**
-     * <!-- MOVED FROM Locations.subscribe -->
      * The previous location of the member.
      */
     previousLocation: unknown;
   }
 }
 
 /**
- * The property names of `LocationsEventMap` are the names of the events emitted by { @link Locations }.
+ * The property names of `LocationsEventMap` are the names of the events emitted by {@link Locations}.
  */
 export interface LocationsEventMap {
   /**
@@ -42,25 +72,10 @@ export interface LocationsEventMap {
 }
 
 /**
- * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/cb5de6a6a40abdcb0d9d5af825928dd62dc1ca64/content/spaces/locations.textile?plain=1#L9-L11) -->
- * The member location feature enables you to track where members are within a space, to see which part of your application they’re interacting with. A location could be the form field they have selected, the cell they’re currently editing in a spreadsheet, or the slide they’re viewing within a slide deck. Multiple members can be present in the same location.
- *
- * Member locations are used to visually display which component other members currently have selected, or are currently active on. Events are emitted whenever a member sets their location, such as when they click on a new cell, or slide. Events are received by members subscribed to location events and the UI component can be highlighted with the active member’s profile data to visually display their location.
+ * [Member locations](https://ably.com/docs/spaces/locations) enable you to track where members are within a {@link Space | space}, to see which part of your application they’re interacting with. A location could be the form field they have selected, the cell they’re currently editing in a spreadsheet, or the slide they’re viewing within a slide deck. Multiple members can be present in the same location.
  *
- * <!-- END WEBSITE DOCUMENTATION -->
+ * Location events are emitted whenever a member changes their location, such as by clicking on a new cell or slide. This enables UI components to be highlighted with the active member's profile data to visually display their location.
  *
- * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/cb5de6a6a40abdcb0d9d5af825928dd62dc1ca64/content/spaces/locations.textile?plain=1#L211-L215) -->
- * ## Member location foundations
- *
- * The Spaces SDK is built upon existing Ably functionality available in Ably’s Core SDKs. Understanding which core features are used to provide the abstractions in the Spaces SDK enables you to manage space state and build additional functionality into your application.
- *
- * Member locations build upon the functionality of the Pub/Sub Channels [presence](https://ably.com/docs/presence-occupancy/presence) feature. Members are entered into the presence set when they {@link Space.enter | enter the space}.
- *
- * <!-- END WEBSITE DOCUMENTATION -->
- *
- * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
- * Handles the tracking of member locations within a space. Inherits from {@link EventEmitter}.
- * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
  */
 export default class Locations extends EventEmitter<LocationsEventMap> {
   private lastLocationUpdate: Record<string, PresenceMember['data']['locationUpdate']['id']> = {};
@@ -103,26 +118,19 @@ export default class Locations extends EventEmitter<LocationsEventMap> {
   }
 
   /**
-   * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/cb5de6a6a40abdcb0d9d5af825928dd62dc1ca64/content/spaces/locations.textile?plain=1#L15-L25) -->
-   * Use the `set()` method to emit a location event in realtime when a member changes their location. This will be received by all location subscribers to inform them of the location change. A `location` can be any JSON-serializable object, such as a slide number or element ID.
+   * Set the location of a member an emit an {@link LocationsEvents.UpdateEvent | `update`} event.
    *
-   * A member must have been { @link Space.enter | entered } into the space to set their location.
+   * A `location` can be any JSON-serializable object, such as a slide number or element ID.
    *
-   * The `set()` method is commonly combined with [`addEventListener()`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget/addEventListener) or a React [synthetic event](https://react.dev/learn/responding-to-events#adding-event-handlers), such as `onClick` or `onHover`.
+   * A member must have been {@link Space.enter | entered} into the space to set their location.
    *
    * The following is an example of a member setting their location to a specific slide number, and element on that slide:
    *
    * ```javascript
    * await space.locations.set({ slide: '3', component: 'slide-title' });
    * ```
-   * <!-- END WEBSITE DOCUMENTATION -->
    *
-   * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
-   * Set your current location. The `location` argument can be any JSON-serializable object. Emits a `locationUpdate` event to all connected clients in this space.
-   * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
-   *
-   * <!-- Second sentence copied from above -->
-   * @param location The new location. Can be any JSON-serializable object, such as a slide number or element ID.
+   * @param location The member's new location. Can be any JSON-serializable object.
    */
   async set(location: unknown) {
     const self = await this.space.members.getSelf();
@@ -138,14 +146,13 @@ export default class Locations extends EventEmitter<LocationsEventMap> {
   /**
    * {@label WITH_EVENTS}
    *
-   * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/cb5de6a6a40abdcb0d9d5af825928dd62dc1ca64/content/spaces/locations.textile?plain=1#L29-L91) -->
-   * Subscribe to location events by registering a listener. Location events are emitted whenever a member changes location by calling {@link set}.
+   * Subscribe to location events by registering a listener. Location events are emitted whenever a member {@link Locations.set | changes} their location.
    *
-   * All location changes are {@link LocationsEventMap.update | `update`} events. When a location update is received, clear the highlight from the UI component of the member’s {@link LocationsEvents.UpdateEvent.previousLocation | `previousLocation`} and add it to {@link LocationsEvents.UpdateEvent.currentLocation | `currentLocation`}.
+   * All location changes are `update` events. When a location update is received, clear the highlight from the UI component of the member’s {@link LocationsEvents.UpdateEvent.previousLocation | `previousLocation`} and add it to {@link LocationsEvents.UpdateEvent.currentLocation | `currentLocation`}.
    *
    * > **Note**
    * >
-   * > A location update is also emitted when a member {@link Space.leave | leaves} a space. The member’s {@link LocationsEvents.UpdateEvent.currentLocation | `currentLocation` } will be `null` for these events so that any UI component highlighting can be cleared.
+   * > A location update is also emitted when a member is {@link MembersEventMap.remove | removed} from a space. The member’s {@link LocationsEvents.UpdateEvent.currentLocation | `currentLocation` } will be `null` for these events so that any UI component highlighting can be cleared. Member location subscription listeners only trigger on events related to members’ locations. Each event only contains the payload of the member that triggered it. Alternatively, {@link Space.subscribe | space state } can be subscribed to which returns an array of all members with their latest state every time any event is triggered.
    *
    * The following is an example of subscribing to location events:
    *
@@ -154,65 +161,9 @@ export default class Locations extends EventEmitter<LocationsEventMap> {
    *   console.log(locationUpdate);
    * });
    * ```
-   * The following is an example payload of a location event. Information about location is returned in {@link LocationsEvents.UpdateEvent.currentLocation | `currentLocation`} and {@link LocationsEvents.UpdateEvent.previousLocation | `previousLocation`}:
    *
-   * ```json
-   * {
-   *   "member": {
-   *     "clientId": "clemons#142",
-   *     "connectionId": "hd9743gjDc",
-   *     "isConnected": true,
-   *     "profileData": {
-   *       "username": "Claire Lemons",
-   *       "avatar": "https://slides-internal.com/users/clemons.png"
-   *     },
-   *     "location": {
-   *       "slide": "3",
-   *       "component": "slide-title"
-   *     },
-   *     "lastEvent": {
-   *       "name": "update",
-   *       "timestamp": 1972395669758
-   *     }
-   *   },
-   *   "previousLocation": {
-   *     "slide": "2",
-   *     "component": null
-   *   },
-   *   "currentLocation": {
-   *     "slide": "3",
-   *     "component": "slide-title"
-   *   }
-   * }
-   * ```
-   * The following are the properties of a location event payload:
-   *
-   * > **Moved documentation**
-   * >
-   * > This documentation has been moved to { @link LocationsEvents.UpdateEvent }.
-   *
-   * > **Further reading**
-   * >
-   * > Member location subscription listeners only trigger on events related to members’ locations. Each event only contains the payload of the member that triggered it. Alternatively, {@link Space.subscribe | space state } can be subscribed to which returns an array of all members with their latest state every time any event is triggered.
-   *
-   * <!-- END WEBSITE DOCUMENTATION -->
-   *
-   * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
-   * Listen to events for locations. See {@link EventEmitter} for overloaded usage.
-   *
-   * Available events:
-   *
-   * - ##### **update**
-   *
-   *   Fires when a member updates their location. The argument supplied to the event listener is an UpdateEvent.
-   *
-   *   ```ts
-   *   space.locations.subscribe('update', (locationUpdate: LocationsEvents.UpdateEvent) => {});
-   *   ```
-   * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
-   *
-   * @param eventOrEvents The event name or an array of event names.
-   * @param listener The listener to add.
+   * @param eventOrEvents An event name, or an array of event names.
+   * @param listener An event listener.
    *
    * @typeParam K A type which allows one or more names of the properties of the {@link LocationsEventMap} type.
    */
@@ -221,9 +172,9 @@ export default class Locations extends EventEmitter<LocationsEventMap> {
     listener?: EventListener<LocationsEventMap, K>,
   ): void;
   /**
-   * Behaves the same as { @link subscribe:WITH_EVENTS | the overload which accepts one or more event names }, but subscribes to _all_ events.
+   * Subscribe to location updates by registering a listener for all events.
    *
-   * @param listener The listener to add.
+   * @param listener An event listener.
    */
   subscribe(listener?: EventListener<LocationsEventMap, keyof LocationsEventMap>): void;
   subscribe<K extends keyof LocationsEventMap>(
@@ -246,31 +197,16 @@ export default class Locations extends EventEmitter<LocationsEventMap> {
   /**
    * {@label WITH_EVENTS}
    *
-   * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/cb5de6a6a40abdcb0d9d5af825928dd62dc1ca64/content/spaces/locations.textile?plain=1#L95-L107) -->
    * Unsubscribe from location events to remove previously registered listeners.
    *
    * The following is an example of removing a listener for location update events:
    *
    * ```javascript
    * space.locations.unsubscribe('update', listener);
    * ```
-   * Or remove all listeners:
    *
-   * ```javascript
-   * space.locations.unsubscribe();
-   * ```
-   * <!-- END WEBSITE DOCUMENTATION -->
-   *
-   * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
-   * Remove all event listeners, all event listeners for an event, or specific listeners. See {@link EventEmitter} for detailed usage.
-   *
-   * ```ts
-   * space.locations.unsubscribe('update');
-   * ```
-   * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
-   *
-   * @param eventOrEvents The event name or an array of event names.
-   * @param listener The listener to remove.
+   * @param eventOrEvents An event name, or an array of event names.
+   * @param listener An event listener.
    *
    * @typeParam K A type which allows one or more names of the properties of the {@link LocationsEventMap} type.
    */
@@ -279,9 +215,15 @@ export default class Locations extends EventEmitter<LocationsEventMap> {
     listener?: EventListener<LocationsEventMap, K>,
   ): void;
   /**
-   * Behaves the same as { @link unsubscribe:WITH_EVENTS | the overload which accepts one or more event names }, but unsubscribes from _all_ events.
+   * Unsubscribe from all events to remove previously registered listeners.
+   *
+   * The following is an example of removing a listener for all events:
+   *
+   * ```javascript
+   * space.locations.unsubscribe(listener);
+   * ```
    *
-   * @param listener The listener to remove.
+   * @param listener An event listener.
    */
   unsubscribe(listener?: EventListener<LocationsEventMap, keyof LocationsEventMap>): void;
   unsubscribe<K extends keyof LocationsEventMap>(
@@ -302,37 +244,27 @@ export default class Locations extends EventEmitter<LocationsEventMap> {
   }
 
   /**
-   * <!-- This is to avoid duplication of the website documentation. -->
-   * See the documentation for {@link getAll}.
+   * Retrieve the location of the current member in a one-off call.
    *
-   * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
-   * Get location for self.
+   * The following is an example of retrieving a member's own location:
    *
-   * Example:
-   *
-   * ```ts
+   * ```javascript
    * const myLocation = await space.locations.getSelf();
    * ```
-   * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
    */
   async getSelf(): Promise<unknown> {
     const self = await this.space.members.getSelf();
     return self ? self.location : null;
   }
 
   /**
-   * <!-- This is to avoid duplication of the website documentation. -->
-   * See the documentation for {@link getAll}.
+   * Retrieve the locations of all members other than the member themselves in a one-off call.
    *
-   * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
-   * Get location for other members
+   * The following is an example of retrieving the locations of all members, except the member themselves:
    *
-   * Example:
-   *
-   * ```ts
+   * ```javascript
    * const otherLocations = await space.locations.getOthers()
    * ```
-   * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
    */
   async getOthers(): Promise<Record<string, unknown>> {
     const members = await this.space.members.getOthers();
@@ -344,75 +276,13 @@ export default class Locations extends EventEmitter<LocationsEventMap> {
   }
 
   /**
-   * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/cb5de6a6a40abdcb0d9d5af825928dd62dc1ca64/content/spaces/locations.textile?plain=1#L111-L172) -->
-   * Member locations can also be retrieved in one-off calls. These are local calls and retrieve the location of members retained in memory by the SDK.
-   *
-   * The following is an example of retrieving a member’s own location:
-   *
-   * ```javascript
-   * const myLocation = await space.locations.getSelf();
-   * ```
-   * The following is an example payload returned by `space.locations.getSelf()`. It will return the properties of the member’s `location`:
-   *
-   * ```json
-   * {
-   *   "slide": "3",
-   *   "component": "slide-title"
-   * }
-   * ```
-   * The following is an example of retrieving the location objects of all members other than the member themselves.
-   *
-   * ```javascript
-   * const othersLocations = await space.locations.getOthers();
-   * ```
-   * The following is an example payload returned by `space.locations.getOthers()`: It will return the properties of all member’s `location` by their `connectionId`:
+   * Retrieve the location of all members in a one-off call.
    *
-   * ```json
-   * {
-   *   "xG6H3lnrCn": {
-   *       "slide": "1",
-   *       "component": "textBox-1"
-   *   },
-   *   "el29SVLktW": {
-   *       "slide": "1",
-   *       "component": "image-2"
-   *   }
-   * }
-   * ```
-   * The following is an example of retrieving the location objects of all members, including the member themselves:
+   * The following is an example of retrieving the locations of all members:
    *
    * ```javascript
    * const allLocations = await space.locations.getAll();
    * ```
-   * The following is an example payload returned by `space.locations.getAll()`. It will return the properties of all member’s `location` by their `connectionId`:
-   *
-   * ```json
-   * {
-   *   "xG6H3lnrCn": {
-   *       "slide": "1",
-   *       "component": "textBox-1"
-   *   },
-   *   "el29SVLktW": {
-   *       "slide": "1",
-   *       "component": "image-2"
-   *   },
-   *   "dieF3291kT": {
-   *       "slide": "3",
-   *       "component": "slide-title"
-   *   }
-   * }
-   * ```
-   * <!-- END WEBSITE DOCUMENTATION -->
-   *
-   * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
-   * Get location for all members.
-   *
-   * Example:
-   *
-   * ```ts
-   * const allLocations = await space.locations.getAll();
-   * ```
-   * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
    */
   async getAll(): Promise<Record<string, unknown>> {
     const members = await this.space.members.getAll();
