Skip to content

Commit

Permalink
wip editing moving etc
Browse files Browse the repository at this point in the history 
I have no idea whether this documentation is going to be _useful_. maybe
that's outside the scope of this work.

TODO move edits into earlier commit

idea is to keep all documentation readable, by always saying when something
has been moved elsewhere. that way we can ship in whatever state this
stuff is in.
  • Loading branch information
@lawrence-forooghian
lawrence-forooghian committed Sep 25, 2023
1 parent 9be643e commit 91d2662
Show file tree
Hide file tree
Showing 7 changed files with 132 additions and 74 deletions.
25 changes: 3 additions & 22 deletions docs_errors.txt
View file
Original file line number Diff line number Diff line change
@@ -1,4 +1,7 @@

[warning] LockStatuses.Pending, defined in ./dist/mjs/types.d.ts, is referenced by LockStatus but not included in the documentation.
[warning] LockStatuses.Locked, defined in ./dist/mjs/types.d.ts, is referenced by LockStatus but not included in the documentation.
[warning] LockStatuses.Unlocked, defined in ./dist/mjs/types.d.ts, is referenced by LockStatus but not included in the documentation.
[warning] LockAttributes, defined in ./dist/mjs/Locks.d.ts, is referenced by LockOptions.attributes but not included in the documentation.
[warning] @ably/spaces, defined in ./dist/mjs/index.d.ts, does not have any documentation.
[warning] Space.client, defined in ./dist/mjs/Space.d.ts, does not have any documentation.
Expand All @@ -7,7 +10,6 @@
[warning] Space.channel, defined in ./dist/mjs/Space.d.ts, does not have any documentation.
[warning] Space.locks, defined in ./dist/mjs/Space.d.ts, does not have any documentation.
[warning] Space.name, defined in ./dist/mjs/Space.d.ts, does not have any documentation.
[warning] Space.enter.profileData, defined in ./dist/mjs/Space.d.ts, does not have any documentation.
[warning] Space.updateProfileData.profileDataOrUpdateFn, defined in ./dist/mjs/Space.d.ts, does not have any documentation.
[warning] Space.updateProfileData.profileDataOrUpdateFn.__type, defined in ./dist/mjs/Space.d.ts, does not have any documentation.
[warning] Space.leave, defined in ./dist/mjs/Space.d.ts, does not have any documentation.
Expand Down Expand Up @@ -56,13 +58,10 @@
[warning] Locations.off.K, defined in ./dist/mjs/utilities/EventEmitter.d.ts, does not have any documentation.
[warning] Locations.listeners.K, defined in ./dist/mjs/utilities/EventEmitter.d.ts, does not have any documentation.
[warning] Locations.once.K, defined in ./dist/mjs/utilities/EventEmitter.d.ts, does not have any documentation.
[warning] LocationsEventMap, defined in ./dist/mjs/Locations.d.ts, does not have any documentation.
[warning] LocationsEventMap.update, defined in ./dist/mjs/Locations.d.ts, does not have any documentation.
[warning] LocationsEvents, defined in ./dist/mjs/Locations.d.ts, does not have any documentation.
[warning] LocationsEvents.UpdateEvent, defined in ./dist/mjs/Locations.d.ts, does not have any documentation.
[warning] LocationsEvents.UpdateEvent.member, defined in ./dist/mjs/Locations.d.ts, does not have any documentation.
[warning] LocationsEvents.UpdateEvent.currentLocation, defined in ./dist/mjs/Locations.d.ts, does not have any documentation.
[warning] LocationsEvents.UpdateEvent.previousLocation, defined in ./dist/mjs/Locations.d.ts, does not have any documentation.
[warning] Locks.get.id, defined in ./dist/mjs/Locks.d.ts, does not have any documentation.
[warning] Locks.acquire.id, defined in ./dist/mjs/Locks.d.ts, does not have any documentation.
[warning] Locks.acquire.opts, defined in ./dist/mjs/Locks.d.ts, does not have any documentation.
Expand Down Expand Up @@ -91,29 +90,11 @@
[warning] Members.off.K, defined in ./dist/mjs/utilities/EventEmitter.d.ts, does not have any documentation.
[warning] Members.listeners.K, defined in ./dist/mjs/utilities/EventEmitter.d.ts, does not have any documentation.
[warning] Members.once.K, defined in ./dist/mjs/utilities/EventEmitter.d.ts, does not have any documentation.
[warning] MembersEventMap, defined in ./dist/mjs/Members.d.ts, does not have any documentation.
[warning] MembersEventMap.leave, defined in ./dist/mjs/Members.d.ts, does not have any documentation.
[warning] MembersEventMap.enter, defined in ./dist/mjs/Members.d.ts, does not have any documentation.
[warning] MembersEventMap.update, defined in ./dist/mjs/Members.d.ts, does not have any documentation.
[warning] MembersEventMap.updateProfile, defined in ./dist/mjs/Members.d.ts, does not have any documentation.
[warning] MembersEventMap.remove, defined in ./dist/mjs/Members.d.ts, does not have any documentation.
[warning] CursorPosition.x, defined in ./dist/mjs/types.d.ts, does not have any documentation.
[warning] CursorPosition.y, defined in ./dist/mjs/types.d.ts, does not have any documentation.
[warning] CursorUpdate.clientId, defined in ./dist/mjs/types.d.ts, does not have any documentation.
[warning] CursorUpdate.connectionId, defined in ./dist/mjs/types.d.ts, does not have any documentation.
[warning] CursorUpdate.position, defined in ./dist/mjs/types.d.ts, does not have any documentation.
[warning] CursorUpdate.data, defined in ./dist/mjs/types.d.ts, does not have any documentation.
[warning] ProfileData, defined in ./dist/mjs/types.d.ts, does not have any documentation.
[warning] SpaceMember.lastEvent.__type, defined in ./dist/mjs/types.d.ts, does not have any documentation.
[warning] SpaceMember.lastEvent.__type.name, defined in ./dist/mjs/types.d.ts, does not have any documentation.
[warning] SpaceMember.lastEvent.__type.timestamp, defined in ./dist/mjs/types.d.ts, does not have any documentation.
[warning] Lock.__type, defined in ./dist/mjs/types.d.ts, does not have any documentation.
[warning] Lock.__type.id, defined in ./dist/mjs/types.d.ts, does not have any documentation.
[warning] Lock.__type.status, defined in ./dist/mjs/types.d.ts, does not have any documentation.
[warning] Lock.__type.member, defined in ./dist/mjs/types.d.ts, does not have any documentation.
[warning] Lock.__type.timestamp, defined in ./dist/mjs/types.d.ts, does not have any documentation.
[warning] Lock.__type.attributes, defined in ./dist/mjs/types.d.ts, does not have any documentation.
[warning] Lock.__type.reason, defined in ./dist/mjs/types.d.ts, does not have any documentation.
[warning] EventEmitter, defined in ./dist/mjs/utilities/EventEmitter.d.ts, does not have any documentation.
[warning] EventEmitter.constructor, defined in ./dist/mjs/utilities/EventEmitter.d.ts, does not have any documentation.
[warning] EventEmitter.constructor.T, defined in ./dist/mjs/utilities/EventEmitter.d.ts, does not have any documentation.
Expand Down
11 changes: 3 additions & 8 deletions src/Cursors.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -132,14 +132,9 @@ export default class Cursors extends EventEmitter<CursorsEventMap> {
* ```
* The following are the properties of a cursor event payload:
*
* | Property | Description | Type |
* |--------------|----------------------------------------------------------------------------------------------------|--------|
* | connectionId | The unique identifier of the member’s [connection](https://ably.com/docs/connect). | String |
* | clientId | The [client identifier](https://ably.com/docs/auth/identified-clients) for the member. | String |
* | position | An object containing the position of a member’s cursor. | Object |
* | position.x | The position of the member’s cursor on the X-axis. | Number |
* | position.y | The position of the member’s cursor on the Y-axis. | Number |
* | data | An optional arbitrary JSON-serializable object containing additional information about the cursor. | Object |
* > **Moved documentation**
* >
* > This documentation has been moved to {@link CursorUpdate} and {@link CursorPosition}.
*
* <!-- END WEBSITE DOCUMENTATION -->
*
Expand Down
25 changes: 15 additions & 10 deletions src/Locations.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,11 +15,23 @@ import SpaceUpdate from './SpaceUpdate.js';
export namespace LocationsEvents {
export interface UpdateEvent {
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;
}
}

/**
* <!-- I WROTE -->
* The property names of `LocationsEventMap` are the names of the events emitted by { @link Locations }.
*/
export interface LocationsEventMap extends EventMap {
update: LocationsEvents.UpdateEvent;
}
Expand Down Expand Up @@ -167,16 +179,9 @@ export default class Locations extends EventEmitter<LocationsEventMap> {
* ```
* The following are the properties of a location event payload:
*
* | Property | Description | Type |
* |----------------------------|-----------------------------------------------------------------------------------------------------------------------|---------|
* | member.clientId | The [client identifier](https://ably.com/docs/auth/identified-clients) for the member. | String |
* | member.connectionId | The unique identifier of the member’s [connection](https://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 {@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 |
* | currentLocation | The new location of the member. | Object |
* > **Moved documentation**
* >
* > This documentation has been moved to { @link LocationsEvents.UpdateEvent }.
*
* > **Further reading**
* >
Expand Down
29 changes: 8 additions & 21 deletions src/Locks.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -55,14 +55,9 @@ export interface LocksEventMap extends EventMap {
*
* A lock will be in one of the following states:
*
* `pending`
* A member has requested a lock by calling [`acquire()`](#acquire).
*
* `locked`
* The lock is confirmed to be held by the requesting member.
*
* `unlocked`
* The lock is confirmed to not be locked by the requesting member, or has been [released](#release) by a member previously holding the lock.
* > **Moved documentation**
* >
* > This documentation has been moved to { @link LockStatuses }.
*
* The following lock state transitions may occur:
*
Expand Down Expand Up @@ -458,19 +453,11 @@ export default class Locks extends EventEmitter<LocksEventMap> {
* ```
* The following are the properties of a lock event payload:
*
* | Property | Description | Type |
* |----------------------------|------------------------------------------------------------------------------------------------------------------------------|-----------|
* | id | The unique ID of the lock request. | String |
* | status | The lock [status](#states) of the event. Will be either `locked` or `unlocked`. | String |
* | timestamp | The timestamp of the lock event. | Number |
* | attributes | The optional attributes of the lock, such as the ID of the component it relates to. | Object |
* | reason | The reason why the `request.status` is `unlocked`. | ErrorInfo |
* | member.clientId | The [client identifier](https://ably.com/docs/auth/identified-clients) for the member. | String |
* | member.connectionId | The unique identifier of the member’s [connection](https://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#events) emitted by the member. Will be one of `enter`, `update`, `leave` or `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 |
* > **Moved documentation**
* >
* > This documentation has been moved to { @link Lock }.
*
* <!-- TODO the documentation for `status` was wrong; it also can be `pending`. -->
*
* <!-- END WEBSITE DOCUMENTATION -->
*
Expand Down
34 changes: 23 additions & 11 deletions src/Members.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,11 +11,31 @@ import type { SpaceMember } from './types.js';
import type { PresenceMember } from './utilities/types.js';
import type Space from './Space.js';

/**
* <!-- I WROTE -->
* The property names of `MembersEventMap` are the names of the events emitted by { @link Members }.
*/
export interface MembersEventMap extends EventMap {
/**
* <!-- COPIED WITH EDITING FROM Members -->
* A member has left the space. The member has either left explicitly by calling { @link Space.leave | `space.leave()` }, or has abruptly disconnected and not re-established a connection within 15 seconds.
*/
leave: SpaceMember;
/**
* <!-- COPIED WITH EDITING FROM Members -->
* A new member has entered the space. The member has either entered explicitly by calling {@link Space.enter | `space.enter()` }, or has attempted to update their profile data before entering a space, which will instead emit an `enter` event.
*/
enter: SpaceMember;
/**
* <!-- COPIED FROM WITH EDITING FROM Members -->
* A member has updated their profile data by calling { @link Space.updateProfileData | `space.updateProfileData()` }.
*/
update: SpaceMember;
updateProfile: SpaceMember;
/**
* <!-- COPIED WITH EDITING FROM Members -->
* A member has been removed from the members list after the { @link SpaceOptions.offlineTimeout | `offlineTimeout` } period has elapsed. This enables members to appear greyed out in the avatar stack to indicate that they recently left for the period of time between their `leave` and `remove` events.
*/
remove: SpaceMember;
}

Expand All @@ -29,17 +49,9 @@ export interface MembersEventMap extends EventMap {
*
* The following four event types are emitted by members:
*
* `enter`
* A new member has entered the space. The member has either entered explicitly by calling [`space.enter()`](/spaces/space#enter), or has attempted to update their profile data before entering a space, which will instead emit an `enter` event.
*
* `update`
* A member has updated their profile data by calling [`space.updateProfileData()`](/spaces/space#update-profile).
*
* `leave`
* A member has left the space. The member has either left explicitly by calling [`space.leave()`](/spaces/space#leave), or has abruptly disconnected and not re-established a connection within 15 seconds.
*
* `remove`
* A member has been removed from the members list after the [`offlineTimeout`](/spaces/space#options) period has elapsed. This enables members to appear greyed out in the avatar stack to indicate that they recently left for the period of time between their `leave` and `remove` events.
* > **Moved documentation**
* >
* > This documentation has been moved to { @link MembersEventMap }.
*
* > **Note**
* >
Expand Down
6 changes: 5 additions & 1 deletion src/Space.ts
View file
Original file line number Diff line number Diff line change
Expand Up @@ -181,7 +181,9 @@ class Space extends EventEmitter<SpaceEventMap> {
* <!-- END WEBSITE DOCUMENTATION -->
*
* <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/14acea6dee7bf3872a3d32d43732f934cbe93a7d/content/spaces/space.textile?plain=1#L71-L82) -->
* Profile data can be set when [entering](#enter) a space. It is optional data that can be used to associate information with a member, such as a preferred username, or profile picture that can be subsequently displayed in their avatar. Profile data can be any arbitrary JSON-serializable object.
* > **Moved documentation**
* >
* > This documentation has been moved to { @link ProfileData }.
*
* Profile data is returned in the payload of all space events.
*
Expand All @@ -203,6 +205,8 @@ class Space extends EventEmitter<SpaceEventMap> {
* type enter = (profileData?: Record<string, unknown>) => Promise<SpaceMember[]>;
* ```
* <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
*
* @param profileData Data to associate with the member who is entering the space.
*/
async enter(profileData: ProfileData = null): Promise<SpaceMember[]> {
return new Promise((resolve) => {
Expand Down
Loading

0 comments on commit 91d2662

Please sign in to comment.