Skip to content

Commit

Permalink
wip turn some stuff into @link
Browse files Browse the repository at this point in the history
  • Loading branch information
@lawrence-forooghian
lawrence-forooghian committed Sep 21, 2023
1 parent 6ae4ec4 commit 74c0d03
Show file tree
Hide file tree
Showing 3 changed files with 27 additions and 22 deletions.
17 changes: 9 additions & 8 deletions src/Locations.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ export interface LocationsEventMap extends EventMap {
* <!-- END WEBSITE DOCUMENTATION -->
*
* <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
* 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}.
* <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
*/
export default class Locations extends EventEmitter<LocationsEventMap> {
Expand Down Expand Up @@ -102,6 +102,7 @@ export default class Locations extends EventEmitter<LocationsEventMap> {
* <!-- END WEBSITE DOCUMENTATION -->
*
* <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
* <!-- TODO what is locationUpdate event, what to link to? -->
* 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
Expand Down Expand Up @@ -134,13 +135,13 @@ export default class Locations extends EventEmitter<LocationsEventMap> {

/**
* <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/14acea6dee7bf3872a3d32d43732f934cbe93a7d/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 [`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:
*
Expand All @@ -149,7 +150,7 @@ 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 `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
* {
Expand Down Expand Up @@ -187,7 +188,7 @@ export default class Locations extends EventEmitter<LocationsEventMap> {
* | 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 |
Expand All @@ -200,7 +201,7 @@ export default class Locations extends EventEmitter<LocationsEventMap> {
* <!-- END WEBSITE DOCUMENTATION -->
*
* <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
* 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:
*
Expand Down Expand Up @@ -247,7 +248,7 @@ export default class Locations extends EventEmitter<LocationsEventMap> {
* <!-- END WEBSITE DOCUMENTATION -->
*
* <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
* 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');
Expand Down
18 changes: 10 additions & 8 deletions src/Space.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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.
*
* <!-- END WEBSITE DOCUMENTATION -->
*
* <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
* 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}.
* <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
*/
class Space extends EventEmitter<SpaceEventMap> {
Expand All @@ -70,7 +70,7 @@ class Space extends EventEmitter<SpaceEventMap> {
readonly options: SpaceOptions;
/**
* <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
* An instance of [Locations](#locations).
* An instance of {@link Locations}.
*
* ```ts
* type locations = instanceof Locations;
Expand All @@ -80,7 +80,7 @@ class Space extends EventEmitter<SpaceEventMap> {
readonly locations: Locations;
/**
* <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
* An instance of [Cursors](#cursors).
* An instance of {@link Cursors}.
*
* ```ts
* type cursors = instanceof Cursors;
Expand All @@ -90,7 +90,7 @@ class Space extends EventEmitter<SpaceEventMap> {
readonly cursors: Cursors;
/**
* <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
* An instance of [Members](#members).
* An instance of {@link Members}.
*
* ```ts
* type members = instanceof Members;
Expand Down Expand Up @@ -166,7 +166,7 @@ class Space extends EventEmitter<SpaceEventMap> {

/**
* <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/14acea6dee7bf3872a3d32d43732f934cbe93a7d/content/spaces/space.textile?plain=1#L43-L55) -->
* 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:
*
Expand Down Expand Up @@ -197,6 +197,7 @@ class Space extends EventEmitter<SpaceEventMap> {
* <!-- END WEBSITE DOCUMENTATION -->
*
* <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
* <!-- TODO what is the link here? -->
* 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
Expand Down Expand Up @@ -237,7 +238,8 @@ class Space extends EventEmitter<SpaceEventMap> {

/**
* <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/14acea6dee7bf3872a3d32d43732f934cbe93a7d/content/spaces/space.textile?plain=1#L86-L103) -->
* 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.
* <!-- TODO link `update` event — I'm not sure which one it's referring to -->
* 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:
*
Expand Down Expand Up @@ -310,7 +312,7 @@ class Space extends EventEmitter<SpaceEventMap> {

/*
* <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/14acea6dee7bf3872a3d32d43732f934cbe93a7d/content/spaces/space.textile?plain=1#L59-L67) -->
* 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:
*
Expand Down
14 changes: 8 additions & 6 deletions src/Spaces.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,7 @@ class Spaces {
private spaces: Record<string, Space> = {};
/**
* <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
* 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;
Expand All @@ -26,7 +26,7 @@ class Spaces {
client: Types.RealtimePromise;
/**
* <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
* 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;
Expand Down Expand Up @@ -79,7 +79,8 @@ class Spaces {

/**
* <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/14acea6dee7bf3872a3d32d43732f934cbe93a7d/content/spaces/space.textile?plain=1#L26-L39) -->
* 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.
* <!-- TODO what is the "`spaces` collection"? -->
* 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:
*
Expand Down Expand Up @@ -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 |
*
Expand All @@ -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:
*
Expand All @@ -146,6 +147,7 @@ class Spaces {
* <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/14acea6dee7bf3872a3d32d43732f934cbe93a7d/content/spaces/cursors.textile?plain=1#L108-L122) -->
* ## Cursor options
*
* <!-- TODO this should be a link to Space, need to fix website docs -->
* 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:
Expand All @@ -163,7 +165,7 @@ class Spaces {
* <!-- END WEBSITE DOCUMENTATION -->
*
* <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
* 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<Space>;
Expand Down

0 comments on commit 74c0d03

Please sign in to comment.