From e9d9fdd189dcd4c604fc3fc1d8917a08337c0b46 Mon Sep 17 00:00:00 2001 From: Dominik Piatek Date: Tue, 29 Aug 2023 13:19:05 +0100 Subject: [PATCH] Documentation tweaks --- README.md | 28 ++++++++++++++-------------- docs/class-definitions.md | 18 +++++++++--------- docs/usage.md | 6 +++--- 3 files changed, 26 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index b7a6db3b..b4f66116 100644 --- a/README.md +++ b/README.md @@ -74,7 +74,7 @@ To instantiate the Spaces SDK, create an [Ably client](https://ably.com/docs/get import Spaces from '@ably-labs/spaces'; import { Realtime } from 'ably'; -const client = new Realtime.Promise({key: "", clientId: ""}); +const client = new Realtime.Promise({ key: "", clientId: "" }); const spaces = new Spaces(client); ``` You can use [basic authentication](https://ably.com/docs/auth/basic) i.e. the API Key directly for testing purposes, however it is strongly recommended that you use [token authentication](https://ably.com/docs/auth/token) in production environments. @@ -107,7 +107,7 @@ space.subscribe('update', (spaceState) => { }); // Enter a space, publishing an update event, including optional profile data -space.enter({ +await space.enter({ username: 'Claire Lemons', avatar: 'https://slides-internal.com/users/clemons.png', }); @@ -136,7 +136,7 @@ The following is an example event payload received by subscribers when a user en ## Space members -The `members` namespace within a Space is a client-side filtered listener optimized for building avatar stacks. Subscribe to members entering, leaving, being removed from the Space (after a timeout) or updating their profile information. +The `members` namespace contains methods dedicated to building avatar stacks. Subscribe to members entering, leaving, being removed from the Space (after a timeout) or updating their profile information. ```ts // Subscribe to all member events in a space @@ -201,17 +201,17 @@ const othersMemberInfo = await space.members.getOthers(); ## Member locations -The `locations` namespace within a Space is a client-side filtered listener optimized for building member locations which enable you to track where users are within an application. A location could be a form field, multiple cells in a spreadsheet or a slide in a slide deck editor. +The `locations` namespace contains methods dedicated to building member locations, enabling you to track where users are within an application. A location could be a form field, multiple cells in a spreadsheet or a slide in a slide deck editor. ```ts // You need to enter a space before publishing your location -space.enter({ +await space.enter({ username: 'Claire Lemons', avatar: 'https://slides-internal.com/users/clemons.png', }); // Publish your location based on the UI element selected -space.locations.set({ slide: '3', component: 'slide-title' }); +await space.locations.set({ slide: '3', component: 'slide-title' }); // Subscribe to location events from all members in a space space.locations.subscribe('update', (locationUpdate) => { @@ -258,22 +258,22 @@ Member locations has methods to get the current snapshot of member state: ```ts // Get a snapshot of all the member locations -const allLocations = space.locations.getAll(); +const allLocations = await space.locations.getAll(); // Get a snapshot of my location -const myLocation = space.locations.getSelf(); +const myLocation = await space.locations.getSelf(); // Get a snapshot of everyone else's locations -const othersLocations = space.locations.getOthers(); +const othersLocations = await space.locations.getOthers(); ``` ## Live cursors -The `cursors` namespace within a Space is a client-side filtered listener optimized for building live cursors which allows you to track a member's pointer position updates across an application. Events can also include associated data, such as pointer attributes and the IDs of associated UI elements: +The `cursors` namespace contains methods dedicated to building live cursors, allowing you to track a member's pointer position updates across an application. Events can also include associated data, such as pointer attributes and the IDs of associated UI elements: ```ts // You need to enter a space before publishing your cursor updates -space.enter({ +await space.enter({ username: 'Claire Lemons', avatar: 'https://slides-internal.com/users/clemons.png', }); @@ -306,11 +306,11 @@ Member cursors has methods to get the current snapshot of member state: ```ts // Get a snapshot of all the cursors -const allCursors = space.cursors.getAll(); +const allCursors = await space.cursors.getAll(); // Get a snapshot of my cursor -const myCursor = space.cursors.getSelf(); +const myCursor = await space.cursors.getSelf(); // Get a snapshot of everyone else's cursors -const othersCursors = space.cursors.getOthers(); +const othersCursors = await space.cursors.getOthers(); ``` diff --git a/docs/class-definitions.md b/docs/class-definitions.md index fdc4fce7..4c087364 100644 --- a/docs/class-definitions.md +++ b/docs/class-definitions.md @@ -224,10 +224,10 @@ space.members.unsubscribe('leave'); #### getSelf() -Returns a Promise which resolves to the [SpaceMember](#spacemember) object relating to the local connection. Will resolve to `undefined` if the client hasn't entered the space yet. +Returns a Promise which resolves to the [SpaceMember](#spacemember) object relating to the local connection. Will resolve to `null` if the client hasn't entered the space yet. ```ts -type getSelf = () => Promise; +type getSelf = () => Promise; ``` Example: @@ -355,7 +355,7 @@ space.locations.unsubscribe('update'); Get location for self. ```ts -type getSelf = () => Promise; +type getSelf = () => Promise; ``` Example: @@ -465,13 +465,13 @@ space.cursors.unsubscribe('update'); Get the last `CursorUpdate` object for self. ```ts -type getSelf = () => ; +type getSelf = () => Promise; ``` Example: ```ts -const selfPosition = space.cursors.getSelf(); +const selfPosition = await space.cursors.getSelf(); ``` #### getAll() @@ -479,13 +479,13 @@ const selfPosition = space.cursors.getSelf(); Get the last `CursorUpdate` object for all the members. ```ts -type getAll = () => Record; +type getAll = () => Promise>; ``` Example: ```ts -const allLatestPositions = space.cursors.getAll(); +const allLatestPositions = await space.cursors.getAll(); ``` #### getOthers() @@ -493,13 +493,13 @@ const allLatestPositions = space.cursors.getAll(); Get the last `CursorUpdate` object for everyone else but yourself. ```ts -type getOthers = () => Record; +type getOthers = () => Promise>; ``` Example: ```ts -const otherPositions = space.cursors.getOthers(); +const otherPositions = await space.cursors.getOthers(); ``` ### Related types diff --git a/docs/usage.md b/docs/usage.md index 62d22c35..82b69a4d 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -96,13 +96,13 @@ space.unsubscribe(); To become a member of a space (and use the other APIs, like location or cursors) a client needs to enter a space. ```ts -space.enter(); +await space.enter(); ``` This method can take an optional object called `profileData` so that users can include convenient metadata to update an avatar stack, such as a username and profile picture. ```ts -space.enter({ +await space.enter({ username: 'Claire Lemons', avatar: 'https://slides-internal.com/users/clemons.png', }); @@ -121,7 +121,7 @@ A leave event does not remove the member immediately from `space.members`. Inste As with `enter`, you can update the `profileData` on leave: ```ts -space.leave({ +await space.leave({ username: 'Claire Lemons', avatar: 'https://slides-internal.com/users/inactive.png', });