diff --git a/src/Locations.ts b/src/Locations.ts index 384b1a06..1f2c7fb5 100644 --- a/src/Locations.ts +++ b/src/Locations.ts @@ -43,7 +43,7 @@ export interface LocationsEventMap extends EventMap { * * * - * Handles the tracking of member locations within a space. Inherits from [EventEmitter](/docs/usage.md#event-emitters). + * Handles the tracking of member locations within a space. Inherits from {@link EventEmitter}. * */ export default class Locations extends EventEmitter { @@ -102,6 +102,7 @@ export default class Locations extends EventEmitter { * * * + * * Set your current location. [Location](#location-1) can be any JSON-serializable object. Emits a [locationUpdate](#locationupdate) event to all connected clients in this space. * * ```ts @@ -134,13 +135,13 @@ export default class Locations extends EventEmitter { /** * - * Subscribe to location events by registering a listener. Location events are emitted whenever a member changes location by calling [`set()`](#set). Use the `subscribe()` method on the `locations` namespace of the space to receive updates. + * Subscribe to location events by registering a listener. Location events are emitted whenever a member changes location by calling {@link set}. Use the `subscribe()` method on the `locations` namespace of the space to receive updates. * - * All location changes are `update` events. When a location update is received, clear the highlight from the UI component of the member’s `previousLocation` and add it to `currentLocation`. + * 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`}. * * > **Note** * > - * > A location update is also emitted when a member [leaves](/spaces/space#leave) a space. The member’s `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 {@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. * * The following is an example of subscribing to location events: * @@ -149,7 +150,7 @@ export default class Locations extends EventEmitter { * console.log(locationUpdate); * }); * ``` - * The following is an example payload of a location event. Information about location is returned in `currentLocation` and `previousLocation`: + * 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 * { @@ -187,7 +188,7 @@ export default class Locations extends EventEmitter { * | member.clientId | The [client identifier](http://ably.com/docs/auth/identified-clients) for the member. | String | * | member.connectionId | The unique identifier of the member’s [connection](http://ably.com/docs/connect). | String | * | member.isConnected | Whether the member is connected to Ably or not. | Boolean | - * | member.lastEvent.name | The most recent [event](/spaces/avatar) emitted by the member. Will be one of `enter`, `update`, `leave` or `remove`. | String | + * | member.lastEvent.name | The most recent [event](/spaces/avatar) emitted by the member. Will be one of {@link MembersEventMap.enter | `enter`}, {@link MembersEventMap.update | `update`}, {@link MembersEventMap.leave | `leave`} or {@link MembersEventMap.remove | `remove`}. | String | * | member.lastEvent.timestamp | The timestamp of the most recently emitted event. | Number | * | member.profileData | The optional [profile data](/spaces/avatar#profile-data) associated with the member. | Object | * | previousLocation | The previous location of the member. | Object | @@ -200,7 +201,7 @@ export default class Locations extends EventEmitter { * * * - * Listen to events for locations. See [EventEmitter](/docs/usage.md#event-emitters) for overloaded usage. + * Listen to events for locations. See {@link EventEmitter} for overloaded usage. * * Available events: * @@ -247,7 +248,7 @@ export default class Locations extends EventEmitter { * * * - * Remove all event listeners, all event listeners for an event, or specific listeners. See [EventEmitter](/docs/usage.md#event-emitters) for detailed usage. + * Remove all event listeners, all event listeners for an event, or specific listeners. See {@link EventEmitter} for detailed usage. * * ```ts * space.locations.unsubscribe('update'); diff --git a/src/Space.ts b/src/Space.ts index eccbbe1b..8292c273 100644 --- a/src/Space.ts +++ b/src/Space.ts @@ -54,14 +54,14 @@ export interface SpaceEventMap extends EventMap { * * The `space` namespace consists of a state object that represents the realtime status of all members in a given virtual space. This includes a list of which members are currently online or have recently left and each member’s location within the application. The position of members’ cursors are excluded from the space state due to their high frequency of updates. In the beta release, which UI components members have locked are also excluded from the space state. * - * Space state can be [subscribed](#subscribe) to in the `space` namespace. Alternatively, subscription listeners can be registered for individual features, such as avatar stack events and member location updates. These individual subscription listeners are intended to provide flexibility when implementing collaborative features. Individual listeners are client-side filtered events, so irrespective of whether you choose to subscribe to the space state or individual listeners, each event only counts as a single message. + * Space state can be {@link subscribe | subscribed} to in the `space` namespace. Alternatively, subscription listeners can be registered for individual features, such as avatar stack events and member location updates. These individual subscription listeners are intended to provide flexibility when implementing collaborative features. Individual listeners are client-side filtered events, so irrespective of whether you choose to subscribe to the space state or individual listeners, each event only counts as a single message. * * To subscribe to any events in a space, you first need to create or retrieve a space. * * * * - * An instance of a Space created using [spaces.get](#get). Inherits from [EventEmitter](/docs/usage.md#event-emitters). + * An instance of a Space created using {@link Spaces.get | spaces.get}. Inherits from {@link EventEmitter}. * */ class Space extends EventEmitter { @@ -70,7 +70,7 @@ class Space extends EventEmitter { readonly options: SpaceOptions; /** * - * An instance of [Locations](#locations). + * An instance of {@link Locations}. * * ```ts * type locations = instanceof Locations; @@ -80,7 +80,7 @@ class Space extends EventEmitter { readonly locations: Locations; /** * - * An instance of [Cursors](#cursors). + * An instance of {@link Cursors}. * * ```ts * type cursors = instanceof Cursors; @@ -90,7 +90,7 @@ class Space extends EventEmitter { readonly cursors: Cursors; /** * - * An instance of [Members](#members). + * An instance of {@link Members}. * * ```ts * type members = instanceof Members; @@ -166,7 +166,7 @@ class Space extends EventEmitter { /** * - * Entering a space will register a client as a member and emit an [`enter`](/spaces/members#events) event to all subscribers. Use the `enter()` method to enter a space. + * Entering a space will register a client as a member and emit an {@link MembersEventMap.enter | `enter` } event to all subscribers. Use the `enter()` method to enter a space. * * Being entered into a space is required for members to: * @@ -197,6 +197,7 @@ class Space extends EventEmitter { * * * + * * Enter the space. Can optionally take `profileData`. This data can be an arbitrary JSON-serializable object which will be attached to the [member object](#spacemember). Returns all current space members. * * ```ts @@ -237,7 +238,8 @@ class Space extends EventEmitter { /** * - * Profile data can be updated at any point after entering a space by calling `updateProfileData()`. This will emit an `update` event. If a client hasn’t yet entered the space, `updateProfileData()` will instead [enter the space](#enter), with the profile data, and emit an [`enter`](/spaces/members#events) event. + * + * Profile data can be updated at any point after entering a space by calling `updateProfileData()`. This will emit an `update` event. If a client hasn’t yet entered the space, `updateProfileData()` will instead {@link enter | enter the space}, with the profile data, and emit an { @link MembersEventMap.enter | `enter` } event. * * The following is an example of updating profile data: * @@ -310,7 +312,7 @@ class Space extends EventEmitter { /* * - * Leaving a space will emit a [`leave`](/spaces/members#events) event to all subscribers. + * Leaving a space will emit a { @link MembersEventMap.leave | `leave` } event to all subscribers. * * The following is an example of explicitly leaving a space: * diff --git a/src/Spaces.ts b/src/Spaces.ts index 3418e3fb..fe69bfef 100644 --- a/src/Spaces.ts +++ b/src/Spaces.ts @@ -16,7 +16,7 @@ class Spaces { private spaces: Record = {}; /** * - * Instance of the [Ably-JS](https://github.com/ably/ably-js#introduction) client that was passed to the [constructor](#constructor). + * Instance of the [Ably-JS](https://github.com/ably/ably-js#introduction) client that was passed to the {@link constructor}. * * ```ts * type client = Ably.RealtimePromise; @@ -26,7 +26,7 @@ class Spaces { client: Types.RealtimePromise; /** * - * Instance of the [Ably-JS](https://github.com/ably/ably-js#introduction) connection, belonging to the client that was passed to the [constructor](#constructor). + * Instance of the [Ably-JS](https://github.com/ably/ably-js#introduction) connection, belonging to the client that was passed to the {@link constructor}. * * ```ts * type connection = Ably.ConnectionPromise; @@ -79,7 +79,8 @@ class Spaces { /** * - * A `space` object is a reference to a single space and is uniquely identified by its unicode string name. A space is created, or an existing space is retrieved from the `spaces` collection using the `get()` method. + * + * A `space` object is a reference to a single space and is uniquely identified by its unicode string name. A space is created, or an existing space is retrieved from the `spaces` collection using the {@link get | `get()`} method. * * The following restrictions apply to space names: * @@ -109,7 +110,7 @@ class Spaces { * | Property | Description | Type | * |-------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------| * | offlineTimeout | Number of milliseconds after a member loses connection or closes their browser window to wait before they are removed from the member list. The default is 120,000ms (2 minutes). | Number | - * | cursors | A [cursor options](/spaces/cursors#options) object for customizing live cursor behavior. | Object | + * | cursors | A {@link CursorsOptions | cursor options} object for customizing live cursor behavior. | Object | * | cursors.outboundBatchInterval | The interval, in milliseconds, at which a batch of cursor positions are published. This is multiplied by the number of members in a space, minus 1. The default value is 100ms. | Number | * | cursors.paginationLimit | The number of pages searched from history for the last published cursor position. The default is 5. | Number | * @@ -127,7 +128,7 @@ class Spaces { * * A space is created as an Ably [channel](/channels). Members [attach](http://ably.com/docs/channels#attach) to the channel and join its [presence set](http://ably.com/docs/presence-occupancy/presence) when they [enter](#enter) the space. Avatar stacks, member locations and component locking are all handled on this channel. * - * To manage the state of the space, you can monitor the [state of the underlying channel](http://ably.com/docs/channels#states). The channel object can be accessed through `space.channel`. + * To manage the state of the space, you can monitor the [state of the underlying channel](http://ably.com/docs/channels#states). The channel object can be accessed through {@link Space.channel | `space.channel`}. * * The following is an example of registering a listener to wait for a channel to become attached: * @@ -146,6 +147,7 @@ class Spaces { * * ## Cursor options * + * * Cursor options are set when creating or retrieving a `space` instance. They are used to control the behavior of live cursors. * * The following cursor options can be set: @@ -163,7 +165,7 @@ class Spaces { * * * - * Get or create a Space instance. Returns a [Space](#space) instance. Configure the space by passing [SpaceOptions](#spaceoptions) as the second argument. + * Get or create a Space instance. Returns a {@link Space} instance. Configure the space by passing {@link SpaceOptions} as the second argument. * * ```ts * type get = (name: string, options?: SpaceOptions) => Promise;