From e4a464116e53d2f0297d425116e0f823da00b4d2 Mon Sep 17 00:00:00 2001
From: Lawrence Forooghian <lawrence@forooghian.com>
Date: Thu, 28 Sep 2023 15:50:38 -0300
Subject: [PATCH 01/30] Remove ability to pass array of event names to
 EventEmitter.prototype.once
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This copies across the change from commit cd4f7b3 in ably-js:

> This functionality is implemented by wrapping the listener argument in
> another listener.  This means that the event emitter does not hold a
> reference to the listener argument (other than that held indirectly
> through the wrapper) and so it is not possible to remove this listener
> using `off(..., listener)`.
>
> The client library specification does not specify a version of `once`
> which accepts an array of event names, and we do not advertise it as
> part of the public API. So, I think the simplest thing is to remove this
> functionality.

The removed code in the current commit also had a bug — the second
argument in the removed code `self.off(eventName, this)` was incorrectly
populated and this made the removed code equivalent to
`self.off(eventName)`; that is, it removed _all_ listeners for the given
event name. I believe that the removal of this code accounts for the
increased expected number of calls to context.spy in one of the tests
here. I’m not sure what reasoning led to the previous expected count of
3 (perhaps the expectation was written just based on the number of calls
observed when running the code), but here’s my reasoning for the
expectation of 4 calls:

Before `context.eventEmitter['off']('myEvent', context.spy)`, the
following calls are relevant to context.spy:

- eventEmitter['on'](context.spy);
- eventEmitter['on']('myEvent', context.spy);
- eventEmitter['on'](['myEvent', 'myOtherEvent', 'myThirdEvent'], context.spy);
- eventEmitter['once'](context.spy);
- eventEmitter['once']('myEvent', context.spy);

After `context.eventEmitter['off']('myEvent', context.spy)`, the
following calls are relevant to context.spy:

- eventEmitter['on'](context.spy);
- eventEmitter['on'](['myEvent' /* no longer applies */, 'myOtherEvent', 'myThirdEvent'], context.spy);
- eventEmitter['once'](context.spy);

After `context.eventEmitter['emit']('myEvent', '')`, the following calls
are relevant to context.spy:

- eventEmitter['on'](context.spy);
- eventEmitter['on'](['myEvent' /* no longer applies *\/, 'myOtherEvent', 'myThirdEvent'], context.spy);

And hence calling `context.eventEmitter['emit']('myOtherEvent', '')`
calls context.spy a further two times.
---
 src/utilities/EventEmitter.test.ts | 15 +-------------
 src/utilities/EventEmitter.ts      | 33 +++++++-----------------------
 2 files changed, 8 insertions(+), 40 deletions(-)

diff --git a/src/utilities/EventEmitter.test.ts b/src/utilities/EventEmitter.test.ts
index aa4c87f6..330102ea 100644
--- a/src/utilities/EventEmitter.test.ts
+++ b/src/utilities/EventEmitter.test.ts
@@ -138,7 +138,6 @@ describe('EventEmitter', () => {
       eventEmitter['once'](altListener);
       eventEmitter['once']('myEvent', context.spy);
       eventEmitter['once']('myEvent', altListener);
-      eventEmitter['once'](['myEvent', 'myOtherEvent', 'myThirdEvent'], altListener);
       context.eventEmitter = eventEmitter;
     });
 
@@ -171,7 +170,7 @@ describe('EventEmitter', () => {
       context.eventEmitter['emit']('myEvent', '');
       expect(context.spy).toHaveBeenCalledTimes(2);
       context.eventEmitter['emit']('myOtherEvent', '');
-      expect(context.spy).toHaveBeenCalledTimes(3);
+      expect(context.spy).toHaveBeenCalledTimes(4);
     });
 
     it('removes a specific listener from multiple events', () => {
@@ -254,18 +253,6 @@ describe('EventEmitter', () => {
       context.eventEmitter['emit']('myEvent', '');
       expect(context.spy).toHaveBeenCalledOnce();
     });
-
-    it('adds a listener to multiple eventOnce fields on calling `once` with a listener and event name; and after emitting any of the events, all are removed', (context) => {
-      context.eventEmitter['once'](['myEvent', 'myOtherEvent', 'myThirdEvent'], context.spy);
-      expect(context.eventEmitter['eventsOnce']['myEvent']).toHaveLength(1);
-      expect(context.eventEmitter['eventsOnce']['myOtherEvent']).toHaveLength(1);
-      expect(context.eventEmitter['eventsOnce']['myThirdEvent']).toHaveLength(1);
-      expect(context.eventEmitter['emit']('myEvent', ''));
-      expect(context.eventEmitter['eventsOnce']['myEvent']).toBe(undefined);
-      expect(context.eventEmitter['eventsOnce']['myOtherEvent']).toBe(undefined);
-      expect(context.eventEmitter['eventsOnce']['myThirdEvent']).toBe(undefined);
-      expect(context.spy).toHaveBeenCalledOnce();
-    });
   });
 
   describe('calling the emit method', () => {
diff --git a/src/utilities/EventEmitter.ts b/src/utilities/EventEmitter.ts
index 247645a2..6c2d1101 100644
--- a/src/utilities/EventEmitter.ts
+++ b/src/utilities/EventEmitter.ts
@@ -223,46 +223,27 @@ export default class EventEmitter<T extends EventMap> {
 
   /**
    * Listen for a single occurrence of an event
-   * @param listenerOrEvents (optional) the name of the event to listen to
+   * @param listenerOrEvent (optional) the name of the event to listen to
    * @param listener (optional) the listener to be called
    */
   once<K extends EventKey<T>>(
-    listenerOrEvents: K | K[] | EventListener<T[K]>,
+    listenerOrEvent: K | EventListener<T[K]>,
     listener?: EventListener<T[K]>,
   ): void | Promise<any> {
     // .once("eventName", () => {})
-    if (isString(listenerOrEvents) && isFunction(listener)) {
-      const listeners = this.eventsOnce[listenerOrEvents] || (this.eventsOnce[listenerOrEvents] = []);
+    if (isString(listenerOrEvent) && isFunction(listener)) {
+      const listeners = this.eventsOnce[listenerOrEvent] || (this.eventsOnce[listenerOrEvent] = []);
       listeners.push(listener);
       return;
     }
 
-    // .once(["eventName"], () => {})
-    if (isArray(listenerOrEvents) && isFunction(listener)) {
-      const self = this;
-
-      listenerOrEvents.forEach(function (eventName) {
-        const listenerWrapper: EventListener<T[K]> = function (this: EventListener<T[K]>, listenerThis) {
-          const innerArgs = Array.prototype.slice.call(arguments) as [params: T[K]];
-          listenerOrEvents.forEach((eventName) => {
-            self.off(eventName, this);
-          });
-
-          listener.apply(listenerThis, innerArgs);
-        };
-        self.once(eventName, listenerWrapper);
-      });
-
-      return;
-    }
-
     // .once(() => {})
-    if (isFunction(listenerOrEvents)) {
-      this.anyOnce.push(listenerOrEvents);
+    if (isFunction(listenerOrEvent)) {
+      this.anyOnce.push(listenerOrEvent);
       return;
     }
 
-    throw new InvalidArgumentError('EventEmitter.once(): invalid arguments:' + inspect([listenerOrEvents, listener]));
+    throw new InvalidArgumentError('EventEmitter.once(): invalid arguments:' + inspect([listenerOrEvent, listener]));
   }
 
   /**

From a3cd2bf5d59bf5dc1096e572b1600ce9a1f9eff3 Mon Sep 17 00:00:00 2001
From: Lawrence Forooghian <lawrence@forooghian.com>
Date: Wed, 27 Sep 2023 15:20:54 -0300
Subject: [PATCH 02/30] Remove unused type `Provider`

---
 src/utilities/types.ts | 13 -------------
 1 file changed, 13 deletions(-)

diff --git a/src/utilities/types.ts b/src/utilities/types.ts
index cd3e2f5a..e1896cbf 100644
--- a/src/utilities/types.ts
+++ b/src/utilities/types.ts
@@ -1,6 +1,5 @@
 import type { Types } from 'ably';
 
-import type { EventKey, EventListener, EventMap } from './EventEmitter.js';
 import type { ProfileData, Lock } from '../types.js';
 
 export type PresenceMember = {
@@ -24,18 +23,6 @@ export type Subset<K> = {
   [attr in keyof K]?: K[attr] extends object ? Subset<K[attr]> : K[attr];
 };
 
-export interface Provider<ProviderEventMap extends EventMap> {
-  subscribe<K extends EventKey<ProviderEventMap>>(
-    listenerOrEvents?: K | K[] | EventListener<ProviderEventMap[K]>,
-    listener?: EventListener<ProviderEventMap[K]>,
-  ): void;
-
-  unsubscribe<K extends EventKey<ProviderEventMap>>(
-    listenerOrEvents?: K | K[] | EventListener<ProviderEventMap[K]>,
-    listener?: EventListener<ProviderEventMap[K]>,
-  ): void;
-}
-
 export type RealtimeMessage = Omit<Types.Message, 'connectionId'> & {
   connectionId: string;
 };

From ad4e91602800b575836c9d65b04c3ae78b36750e Mon Sep 17 00:00:00 2001
From: Lawrence Forooghian <lawrence@forooghian.com>
Date: Wed, 20 Sep 2023 16:13:27 -0300
Subject: [PATCH 03/30] Make naming of event map types consistent

Make them all of the form "EventMap" prefixed by the name of the class
that emits them.

Note that the use of "EventMap" as opposed to "EventsMap" naming is also
consistent with the naming used by TypeScript for the DOM
event maps (e.g. [1]).

[1] https://github.com/microsoft/TypeScript/blob/f3dad2a07d007c40d260f13d6b087a2d5685d12d/src/lib/dom.generated.d.ts#L2418-L2422
---
 src/Locks.ts   | 16 ++++++++--------
 src/Members.ts | 16 ++++++++--------
 src/Space.ts   | 16 ++++++++--------
 3 files changed, 24 insertions(+), 24 deletions(-)

diff --git a/src/Locks.ts b/src/Locks.ts
index 8e6eba2f..b81ea078 100644
--- a/src/Locks.ts
+++ b/src/Locks.ts
@@ -23,11 +23,11 @@ interface LockOptions {
   attributes: LockAttributes;
 }
 
-type LockEventMap = {
+type LocksEventMap = {
   update: Lock;
 };
 
-export default class Locks extends EventEmitter<LockEventMap> {
+export default class Locks extends EventEmitter<LocksEventMap> {
   // locks tracks the local state of locks, which is used to determine whether
   // a lock's status has changed when processing presence updates.
   //
@@ -135,9 +135,9 @@ export default class Locks extends EventEmitter<LockEventMap> {
     this.deleteLock(id, self.connectionId);
   }
 
-  subscribe<K extends EventKey<LockEventMap>>(
-    listenerOrEvents?: K | K[] | EventListener<LockEventMap[K]>,
-    listener?: EventListener<LockEventMap[K]>,
+  subscribe<K extends EventKey<LocksEventMap>>(
+    listenerOrEvents?: K | K[] | EventListener<LocksEventMap[K]>,
+    listener?: EventListener<LocksEventMap[K]>,
   ) {
     try {
       super.on(listenerOrEvents, listener);
@@ -152,9 +152,9 @@ export default class Locks extends EventEmitter<LockEventMap> {
     }
   }
 
-  unsubscribe<K extends EventKey<LockEventMap>>(
-    listenerOrEvents?: K | K[] | EventListener<LockEventMap[K]>,
-    listener?: EventListener<LockEventMap[K]>,
+  unsubscribe<K extends EventKey<LocksEventMap>>(
+    listenerOrEvents?: K | K[] | EventListener<LocksEventMap[K]>,
+    listener?: EventListener<LocksEventMap[K]>,
   ) {
     try {
       super.off(listenerOrEvents, listener);
diff --git a/src/Members.ts b/src/Members.ts
index 2edae1f3..6ca88b73 100644
--- a/src/Members.ts
+++ b/src/Members.ts
@@ -10,7 +10,7 @@ import type { SpaceMember } from './types.js';
 import type { PresenceMember } from './utilities/types.js';
 import type Space from './Space.js';
 
-type MemberEventsMap = {
+type MembersEventMap = {
   leave: SpaceMember;
   enter: SpaceMember;
   update: SpaceMember;
@@ -18,7 +18,7 @@ type MemberEventsMap = {
   remove: SpaceMember;
 };
 
-class Members extends EventEmitter<MemberEventsMap> {
+class Members extends EventEmitter<MembersEventMap> {
   private lastMemberUpdate: Record<string, PresenceMember['data']['profileUpdate']['id']> = {};
   private leavers: Leavers;
 
@@ -69,9 +69,9 @@ class Members extends EventEmitter<MemberEventsMap> {
     return members.filter((m) => m.connectionId !== this.space.connectionId);
   }
 
-  subscribe<K extends EventKey<MemberEventsMap>>(
-    listenerOrEvents?: K | K[] | EventListener<MemberEventsMap[K]>,
-    listener?: EventListener<MemberEventsMap[K]>,
+  subscribe<K extends EventKey<MembersEventMap>>(
+    listenerOrEvents?: K | K[] | EventListener<MembersEventMap[K]>,
+    listener?: EventListener<MembersEventMap[K]>,
   ) {
     try {
       super.on(listenerOrEvents, listener);
@@ -86,9 +86,9 @@ class Members extends EventEmitter<MemberEventsMap> {
     }
   }
 
-  unsubscribe<K extends EventKey<MemberEventsMap>>(
-    listenerOrEvents?: K | K[] | EventListener<MemberEventsMap[K]>,
-    listener?: EventListener<MemberEventsMap[K]>,
+  unsubscribe<K extends EventKey<MembersEventMap>>(
+    listenerOrEvents?: K | K[] | EventListener<MembersEventMap[K]>,
+    listener?: EventListener<MembersEventMap[K]>,
   ) {
     try {
       super.off(listenerOrEvents, listener);
diff --git a/src/Space.ts b/src/Space.ts
index 50dec7d2..a93b9959 100644
--- a/src/Space.ts
+++ b/src/Space.ts
@@ -29,11 +29,11 @@ const SPACE_OPTIONS_DEFAULTS = {
   },
 };
 
-type SpaceEventsMap = {
+type SpaceEventMap = {
   update: { members: SpaceMember[] };
 };
 
-class Space extends EventEmitter<SpaceEventsMap> {
+class Space extends EventEmitter<SpaceEventMap> {
   readonly channelName: string;
   readonly connectionId: string | undefined;
   readonly options: SpaceOptions;
@@ -177,9 +177,9 @@ class Space extends EventEmitter<SpaceEventsMap> {
     return { members };
   }
 
-  subscribe<K extends EventKey<SpaceEventsMap>>(
-    listenerOrEvents?: K | K[] | EventListener<SpaceEventsMap[K]>,
-    listener?: EventListener<SpaceEventsMap[K]>,
+  subscribe<K extends EventKey<SpaceEventMap>>(
+    listenerOrEvents?: K | K[] | EventListener<SpaceEventMap[K]>,
+    listener?: EventListener<SpaceEventMap[K]>,
   ) {
     try {
       super.on(listenerOrEvents, listener);
@@ -194,9 +194,9 @@ class Space extends EventEmitter<SpaceEventsMap> {
     }
   }
 
-  unsubscribe<K extends EventKey<SpaceEventsMap>>(
-    listenerOrEvents?: K | K[] | EventListener<SpaceEventsMap[K]>,
-    listener?: EventListener<SpaceEventsMap[K]>,
+  unsubscribe<K extends EventKey<SpaceEventMap>>(
+    listenerOrEvents?: K | K[] | EventListener<SpaceEventMap[K]>,
+    listener?: EventListener<SpaceEventMap[K]>,
   ) {
     try {
       super.off(listenerOrEvents, listener);

From c51b23e26d42eddf8847eb7dbe122b4a1963ab04 Mon Sep 17 00:00:00 2001
From: Lawrence Forooghian <lawrence@forooghian.com>
Date: Wed, 20 Sep 2023 15:03:37 -0300
Subject: [PATCH 04/30] =?UTF-8?q?Mark=20non-public=20API=20where=20we=20ha?=
 =?UTF-8?q?ven=E2=80=99t=20already?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

I am shortly going to be adding documentation comments to the codebase,
but only for public API. I’ll then use TypeDoc to generate documentation
based on these comments.

So, to avoid TypeDoc errors of the form "X does not have any
documentation" for non-public API, I’m marking the non-public API as
`private` or `@internal`, and will configure TypeDoc to ignore any
such-marked items.

My guessing of what constitutes public API is done based on what’s
mentioned in the documentation on ably.com and what’s used in the demo
code bundled in this repo.
---
 src/Cursors.ts                |  1 +
 src/Locations.ts              |  2 ++
 src/Locks.ts                  | 12 ++++++++----
 src/Members.ts                |  7 +++++--
 src/Space.ts                  |  3 ++-
 src/utilities/EventEmitter.ts | 11 ++++++++++-
 6 files changed, 28 insertions(+), 8 deletions(-)

diff --git a/src/Cursors.ts b/src/Cursors.ts
index e3318bc2..003e8f49 100644
--- a/src/Cursors.ts
+++ b/src/Cursors.ts
@@ -31,6 +31,7 @@ export default class Cursors extends EventEmitter<CursorsEventMap> {
 
   public channel?: Types.RealtimeChannelPromise;
 
+  /** @internal */
   constructor(private space: Space) {
     super();
 
diff --git a/src/Locations.ts b/src/Locations.ts
index f2b57106..58936210 100644
--- a/src/Locations.ts
+++ b/src/Locations.ts
@@ -18,10 +18,12 @@ type LocationsEventMap = {
 export default class Locations extends EventEmitter<LocationsEventMap> {
   private lastLocationUpdate: Record<string, PresenceMember['data']['locationUpdate']['id']> = {};
 
+  /** @internal */
   constructor(private space: Space, private presenceUpdate: Space['presenceUpdate']) {
     super();
   }
 
+  /** @internal */
   async processPresenceMessage(message: PresenceMember) {
     // Only an update action is currently a valid location update.
     if (message.action !== 'update') return;
diff --git a/src/Locks.ts b/src/Locks.ts
index b81ea078..315acd20 100644
--- a/src/Locks.ts
+++ b/src/Locks.ts
@@ -36,6 +36,7 @@ export default class Locks extends EventEmitter<LocksEventMap> {
   // have requested.
   private locks: Map<string, Map<string, Lock>>;
 
+  /** @internal */
   constructor(private space: Space, private presenceUpdate: Space['presenceUpdate']) {
     super();
     this.locks = new Map();
@@ -169,6 +170,7 @@ export default class Locks extends EventEmitter<LocksEventMap> {
     }
   }
 
+  /** @internal */
   async processPresenceMessage(message: Types.PresenceMessage) {
     const member = await this.space.members.getByConnectionId(message.connectionId);
     if (!member) return;
@@ -222,7 +224,7 @@ export default class Locks extends EventEmitter<LocksEventMap> {
   //
   // TODO: remove this once the Ably system processes PENDING requests
   //       internally using this same logic.
-  processPending(member: SpaceMember, pendingLock: Lock) {
+  private processPending(member: SpaceMember, pendingLock: Lock) {
     // if the requested lock ID is not currently locked, then mark the PENDING
     // lock request as LOCKED
     const lock = this.get(pendingLock.id);
@@ -266,18 +268,19 @@ export default class Locks extends EventEmitter<LocksEventMap> {
     pendingLock.reason = ERR_LOCK_IS_LOCKED();
   }
 
-  updatePresence(self: SpaceMember) {
+  private updatePresence(self: SpaceMember) {
     const update = new SpaceUpdate({ self, extras: this.getLockExtras(self.connectionId) });
     return this.presenceUpdate(update.noop());
   }
 
+  /** @internal */
   getLock(id: string, connectionId: string): Lock | undefined {
     const locks = this.locks.get(id);
     if (!locks) return;
     return locks.get(connectionId);
   }
 
-  setLock(lock: Lock) {
+  private setLock(lock: Lock) {
     let locks = this.locks.get(lock.id);
     if (!locks) {
       locks = new Map();
@@ -286,7 +289,7 @@ export default class Locks extends EventEmitter<LocksEventMap> {
     locks.set(lock.member.connectionId, lock);
   }
 
-  deleteLock(id: string, connectionId: string) {
+  private deleteLock(id: string, connectionId: string) {
     const locks = this.locks.get(id);
     if (!locks) return;
     return locks.delete(connectionId);
@@ -306,6 +309,7 @@ export default class Locks extends EventEmitter<LocksEventMap> {
     return requests;
   }
 
+  /** @internal */
   getLockExtras(connectionId: string): PresenceMember['extras'] {
     const locks = this.getLocksForConnectionId(connectionId);
     if (locks.length === 0) return;
diff --git a/src/Members.ts b/src/Members.ts
index 6ca88b73..6c3b9611 100644
--- a/src/Members.ts
+++ b/src/Members.ts
@@ -22,11 +22,13 @@ class Members extends EventEmitter<MembersEventMap> {
   private lastMemberUpdate: Record<string, PresenceMember['data']['profileUpdate']['id']> = {};
   private leavers: Leavers;
 
+  /** @internal */
   constructor(private space: Space) {
     super();
     this.leavers = new Leavers(this.space.options.offlineTimeout);
   }
 
+  /** @internal */
   async processPresenceMessage(message: PresenceMember) {
     const { action, connectionId } = message;
     const isLeaver = !!this.leavers.getByConnectionId(connectionId);
@@ -103,12 +105,13 @@ class Members extends EventEmitter<MembersEventMap> {
     }
   }
 
+  /** @internal */
   async getByConnectionId(connectionId: string): Promise<SpaceMember | null> {
     const members = await this.getAll();
     return members.find((m) => m.connectionId === connectionId) ?? null;
   }
 
-  createMember(message: PresenceMember): SpaceMember {
+  private createMember(message: PresenceMember): SpaceMember {
     return {
       clientId: message.clientId,
       connectionId: message.connectionId,
@@ -122,7 +125,7 @@ class Members extends EventEmitter<MembersEventMap> {
     };
   }
 
-  async onMemberOffline(member: SpaceMember) {
+  private async onMemberOffline(member: SpaceMember) {
     this.leavers.removeLeaver(member.connectionId);
 
     this.emit('remove', member);
diff --git a/src/Space.ts b/src/Space.ts
index a93b9959..a82c6327 100644
--- a/src/Space.ts
+++ b/src/Space.ts
@@ -34,7 +34,7 @@ type SpaceEventMap = {
 };
 
 class Space extends EventEmitter<SpaceEventMap> {
-  readonly channelName: string;
+  private readonly channelName: string;
   readonly connectionId: string | undefined;
   readonly options: SpaceOptions;
   readonly locations: Locations;
@@ -44,6 +44,7 @@ class Space extends EventEmitter<SpaceEventMap> {
   readonly locks: Locks;
   readonly name: string;
 
+  /** @internal */
   constructor(name: string, readonly client: Types.RealtimePromise, options?: Subset<SpaceOptions>) {
     super();
 
diff --git a/src/utilities/EventEmitter.ts b/src/utilities/EventEmitter.ts
index 6c2d1101..f23289a8 100644
--- a/src/utilities/EventEmitter.ts
+++ b/src/utilities/EventEmitter.ts
@@ -70,11 +70,18 @@ export type EventKey<T extends EventMap> = string & keyof T;
 export type EventListener<T> = (params: T) => void;
 
 export default class EventEmitter<T extends EventMap> {
+  /** @internal */
   any: Array<Function>;
+  /** @internal */
   events: Record<string, Function[]>;
+  /** @internal */
   anyOnce: Array<Function>;
+  /** @internal */
   eventsOnce: Record<string, Function[]>;
 
+  /**
+   * @internal
+   */
   constructor() {
     this.any = [];
     this.events = Object.create(null);
@@ -188,6 +195,8 @@ export default class EventEmitter<T extends EventMap> {
   }
 
   /**
+   * @internal
+   *
    * Emit an event
    * @param event the event name
    * @param arg the arguments to pass to the listener
@@ -247,7 +256,7 @@ export default class EventEmitter<T extends EventMap> {
   }
 
   /**
-   * Private API
+   * @internal
    *
    * Listen for a single occurrence of a state event and fire immediately if currentState matches targetState
    * @param targetState the name of the state event to listen to

From aaf47a21725b17842b2f8e6ceba42e9801a716aa Mon Sep 17 00:00:00 2001
From: Lawrence Forooghian <lawrence@forooghian.com>
Date: Wed, 20 Sep 2023 14:43:31 -0300
Subject: [PATCH 05/30] Export all types that are referenced by exported types
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

As mentioned in ad4e916, I’ll be adding TypeDoc to the project. The aim
of the change in this commit is to avoid TypeDoc warnings of the form "X
(...) is referenced by Y but not included in the documentation."
---
 src/Cursors.ts   |  2 +-
 src/Locations.ts |  2 +-
 src/Locks.ts     |  4 ++--
 src/Members.ts   |  2 +-
 src/Space.ts     |  2 +-
 src/index.ts     | 11 ++++++++++-
 6 files changed, 16 insertions(+), 7 deletions(-)

diff --git a/src/Cursors.ts b/src/Cursors.ts
index 003e8f49..3a823169 100644
--- a/src/Cursors.ts
+++ b/src/Cursors.ts
@@ -16,7 +16,7 @@ import type { CursorsOptions, CursorUpdate } from './types.js';
 import type { RealtimeMessage } from './utilities/types.js';
 import { ERR_NOT_ENTERED_SPACE } from './Errors.js';
 
-type CursorsEventMap = {
+export type CursorsEventMap = {
   update: CursorUpdate;
 };
 
diff --git a/src/Locations.ts b/src/Locations.ts
index 58936210..8ae53523 100644
--- a/src/Locations.ts
+++ b/src/Locations.ts
@@ -11,7 +11,7 @@ import type Space from './Space.js';
 import { ERR_NOT_ENTERED_SPACE } from './Errors.js';
 import SpaceUpdate from './SpaceUpdate.js';
 
-type LocationsEventMap = {
+export type LocationsEventMap = {
   update: { member: SpaceMember; currentLocation: unknown; previousLocation: unknown };
 };
 
diff --git a/src/Locks.ts b/src/Locks.ts
index 315acd20..2f513f70 100644
--- a/src/Locks.ts
+++ b/src/Locks.ts
@@ -19,11 +19,11 @@ export class LockAttributes extends Map<string, string> {
   }
 }
 
-interface LockOptions {
+export interface LockOptions {
   attributes: LockAttributes;
 }
 
-type LocksEventMap = {
+export type LocksEventMap = {
   update: Lock;
 };
 
diff --git a/src/Members.ts b/src/Members.ts
index 6c3b9611..67330e38 100644
--- a/src/Members.ts
+++ b/src/Members.ts
@@ -10,7 +10,7 @@ import type { SpaceMember } from './types.js';
 import type { PresenceMember } from './utilities/types.js';
 import type Space from './Space.js';
 
-type MembersEventMap = {
+export type MembersEventMap = {
   leave: SpaceMember;
   enter: SpaceMember;
   update: SpaceMember;
diff --git a/src/Space.ts b/src/Space.ts
index a82c6327..511ed439 100644
--- a/src/Space.ts
+++ b/src/Space.ts
@@ -29,7 +29,7 @@ const SPACE_OPTIONS_DEFAULTS = {
   },
 };
 
-type SpaceEventMap = {
+export type SpaceEventMap = {
   update: { members: SpaceMember[] };
 };
 
diff --git a/src/index.ts b/src/index.ts
index f51aacdb..a6a8fec1 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -1,6 +1,11 @@
 import Spaces from './Spaces.js';
 
-export type Space = Awaited<ReturnType<Spaces['get']>>;
+export type { default as Space, SpaceEventMap } from './Space.js';
+
+export type { default as Cursors, CursorsEventMap } from './Cursors.js';
+export type { default as Locations, LocationsEventMap } from './Locations.js';
+export type { default as Locks, LocksEventMap, LockOptions } from './Locks.js';
+export type { default as Members, MembersEventMap } from './Members.js';
 
 // Can be changed to * when we update to TS5
 
@@ -19,3 +24,7 @@ export type {
 } from './types.js';
 
 export { LockAttributes } from './Locks.js';
+
+export type { default as EventEmitter, EventListener, EventKey, EventMap } from './utilities/EventEmitter.js';
+
+export type { Subset } from './utilities/types.js';

From f4a949882d329e05d53d7c76971e0d843f98482c Mon Sep 17 00:00:00 2001
From: Lawrence Forooghian <lawrence@forooghian.com>
Date: Thu, 21 Sep 2023 13:56:25 -0300
Subject: [PATCH 06/30] Extract a couple of events to their own types

So that I can write documentation comments for them.
---
 src/Locations.ts | 10 +++++++++-
 src/Space.ts     |  8 +++++++-
 src/index.ts     |  4 ++--
 3 files changed, 18 insertions(+), 4 deletions(-)

diff --git a/src/Locations.ts b/src/Locations.ts
index 8ae53523..b2ac3d27 100644
--- a/src/Locations.ts
+++ b/src/Locations.ts
@@ -11,8 +11,16 @@ import type Space from './Space.js';
 import { ERR_NOT_ENTERED_SPACE } from './Errors.js';
 import SpaceUpdate from './SpaceUpdate.js';
 
+export namespace LocationsEvents {
+  export interface UpdateEvent {
+    member: SpaceMember;
+    currentLocation: unknown;
+    previousLocation: unknown;
+  }
+}
+
 export type LocationsEventMap = {
-  update: { member: SpaceMember; currentLocation: unknown; previousLocation: unknown };
+  update: LocationsEvents.UpdateEvent;
 };
 
 export default class Locations extends EventEmitter<LocationsEventMap> {
diff --git a/src/Space.ts b/src/Space.ts
index 511ed439..7a4bebc8 100644
--- a/src/Space.ts
+++ b/src/Space.ts
@@ -29,8 +29,14 @@ const SPACE_OPTIONS_DEFAULTS = {
   },
 };
 
+export namespace SpaceEvents {
+  export interface UpdateEvent {
+    members: SpaceMember[];
+  }
+}
+
 export type SpaceEventMap = {
-  update: { members: SpaceMember[] };
+  update: SpaceEvents.UpdateEvent;
 };
 
 class Space extends EventEmitter<SpaceEventMap> {
diff --git a/src/index.ts b/src/index.ts
index a6a8fec1..1a7da0ca 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -1,9 +1,9 @@
 import Spaces from './Spaces.js';
 
-export type { default as Space, SpaceEventMap } from './Space.js';
+export type { default as Space, SpaceEventMap, SpaceEvents } from './Space.js';
 
 export type { default as Cursors, CursorsEventMap } from './Cursors.js';
-export type { default as Locations, LocationsEventMap } from './Locations.js';
+export type { default as Locations, LocationsEventMap, LocationsEvents } from './Locations.js';
 export type { default as Locks, LocksEventMap, LockOptions } from './Locks.js';
 export type { default as Members, MembersEventMap } from './Members.js';
 

From 9e27b5e7b6518a1e964760e154de5927a3ceae03 Mon Sep 17 00:00:00 2001
From: Lawrence Forooghian <lawrence@forooghian.com>
Date: Wed, 27 Sep 2023 15:27:14 -0300
Subject: [PATCH 07/30] Get rid of EventMap and EventKey types
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

I want to convert the *EventMap types from types to interfaces, but the
EventMap type complicates this. So, let’s get rid of it and the
accompanying EventKey type. I can’t see a compelling reason for their
existence. Removing them also means fewer types for users to understand,
and fewer types for us to document.
---
 src/Cursors.ts                     | 13 ++++------
 src/Locations.ts                   | 11 +++------
 src/Locks.ts                       | 11 +++------
 src/Members.ts                     | 11 +++------
 src/Space.ts                       | 11 +++------
 src/index.ts                       |  2 +-
 src/utilities/EventEmitter.test.ts |  2 +-
 src/utilities/EventEmitter.ts      | 38 ++++++++++++++++--------------
 src/utilities/is.ts                |  2 +-
 9 files changed, 39 insertions(+), 62 deletions(-)

diff --git a/src/Cursors.ts b/src/Cursors.ts
index 3a823169..da9cb764 100644
--- a/src/Cursors.ts
+++ b/src/Cursors.ts
@@ -3,12 +3,7 @@ import { Types } from 'ably';
 import Space from './Space.js';
 import CursorBatching from './CursorBatching.js';
 import CursorDispensing from './CursorDispensing.js';
-import EventEmitter, {
-  InvalidArgumentError,
-  inspect,
-  type EventKey,
-  type EventListener,
-} from './utilities/EventEmitter.js';
+import EventEmitter, { InvalidArgumentError, inspect, type EventListener } from './utilities/EventEmitter.js';
 import CursorHistory from './CursorHistory.js';
 import { CURSOR_UPDATE } from './CursorConstants.js';
 
@@ -91,7 +86,7 @@ export default class Cursors extends EventEmitter<CursorsEventMap> {
     return !this.emitterHasListeners(subscriptions);
   }
 
-  private emitterHasListeners = (emitter: EventEmitter<{}>) => {
+  private emitterHasListeners = <T>(emitter: EventEmitter<T>) => {
     const flattenEvents = (obj: Record<string, Function[]>) =>
       Object.entries(obj)
         .map((_, v) => v)
@@ -105,7 +100,7 @@ export default class Cursors extends EventEmitter<CursorsEventMap> {
     );
   };
 
-  subscribe<K extends EventKey<CursorsEventMap>>(
+  subscribe<K extends keyof CursorsEventMap>(
     listenerOrEvents?: K | K[] | EventListener<CursorsEventMap[K]>,
     listener?: EventListener<CursorsEventMap[K]>,
   ) {
@@ -130,7 +125,7 @@ export default class Cursors extends EventEmitter<CursorsEventMap> {
     }
   }
 
-  unsubscribe<K extends EventKey<CursorsEventMap>>(
+  unsubscribe<K extends keyof CursorsEventMap>(
     listenerOrEvents?: K | K[] | EventListener<CursorsEventMap[K]>,
     listener?: EventListener<CursorsEventMap[K]>,
   ) {
diff --git a/src/Locations.ts b/src/Locations.ts
index b2ac3d27..a5118786 100644
--- a/src/Locations.ts
+++ b/src/Locations.ts
@@ -1,9 +1,4 @@
-import EventEmitter, {
-  InvalidArgumentError,
-  inspect,
-  type EventKey,
-  type EventListener,
-} from './utilities/EventEmitter.js';
+import EventEmitter, { InvalidArgumentError, inspect, type EventListener } from './utilities/EventEmitter.js';
 
 import type { SpaceMember } from './types.js';
 import type { PresenceMember } from './utilities/types.js';
@@ -71,7 +66,7 @@ export default class Locations extends EventEmitter<LocationsEventMap> {
     await this.presenceUpdate(update.updateLocation(location));
   }
 
-  subscribe<K extends EventKey<LocationsEventMap>>(
+  subscribe<K extends keyof LocationsEventMap>(
     listenerOrEvents?: K | K[] | EventListener<LocationsEventMap[K]>,
     listener?: EventListener<LocationsEventMap[K]>,
   ) {
@@ -88,7 +83,7 @@ export default class Locations extends EventEmitter<LocationsEventMap> {
     }
   }
 
-  unsubscribe<K extends EventKey<LocationsEventMap>>(
+  unsubscribe<K extends keyof LocationsEventMap>(
     listenerOrEvents?: K | K[] | EventListener<LocationsEventMap[K]>,
     listener?: EventListener<LocationsEventMap[K]>,
   ) {
diff --git a/src/Locks.ts b/src/Locks.ts
index 2f513f70..5b646a39 100644
--- a/src/Locks.ts
+++ b/src/Locks.ts
@@ -4,12 +4,7 @@ import Space from './Space.js';
 import type { Lock, SpaceMember } from './types.js';
 import type { PresenceMember } from './utilities/types.js';
 import { ERR_LOCK_IS_LOCKED, ERR_LOCK_INVALIDATED, ERR_LOCK_REQUEST_EXISTS, ERR_NOT_ENTERED_SPACE } from './Errors.js';
-import EventEmitter, {
-  InvalidArgumentError,
-  inspect,
-  type EventKey,
-  type EventListener,
-} from './utilities/EventEmitter.js';
+import EventEmitter, { InvalidArgumentError, inspect, type EventListener } from './utilities/EventEmitter.js';
 
 import SpaceUpdate from './SpaceUpdate.js';
 
@@ -136,7 +131,7 @@ export default class Locks extends EventEmitter<LocksEventMap> {
     this.deleteLock(id, self.connectionId);
   }
 
-  subscribe<K extends EventKey<LocksEventMap>>(
+  subscribe<K extends keyof LocksEventMap>(
     listenerOrEvents?: K | K[] | EventListener<LocksEventMap[K]>,
     listener?: EventListener<LocksEventMap[K]>,
   ) {
@@ -153,7 +148,7 @@ export default class Locks extends EventEmitter<LocksEventMap> {
     }
   }
 
-  unsubscribe<K extends EventKey<LocksEventMap>>(
+  unsubscribe<K extends keyof LocksEventMap>(
     listenerOrEvents?: K | K[] | EventListener<LocksEventMap[K]>,
     listener?: EventListener<LocksEventMap[K]>,
   ) {
diff --git a/src/Members.ts b/src/Members.ts
index 67330e38..f0461f4e 100644
--- a/src/Members.ts
+++ b/src/Members.ts
@@ -1,9 +1,4 @@
-import EventEmitter, {
-  InvalidArgumentError,
-  inspect,
-  type EventKey,
-  type EventListener,
-} from './utilities/EventEmitter.js';
+import EventEmitter, { InvalidArgumentError, inspect, type EventListener } from './utilities/EventEmitter.js';
 import Leavers from './Leavers.js';
 
 import type { SpaceMember } from './types.js';
@@ -71,7 +66,7 @@ class Members extends EventEmitter<MembersEventMap> {
     return members.filter((m) => m.connectionId !== this.space.connectionId);
   }
 
-  subscribe<K extends EventKey<MembersEventMap>>(
+  subscribe<K extends keyof MembersEventMap>(
     listenerOrEvents?: K | K[] | EventListener<MembersEventMap[K]>,
     listener?: EventListener<MembersEventMap[K]>,
   ) {
@@ -88,7 +83,7 @@ class Members extends EventEmitter<MembersEventMap> {
     }
   }
 
-  unsubscribe<K extends EventKey<MembersEventMap>>(
+  unsubscribe<K extends keyof MembersEventMap>(
     listenerOrEvents?: K | K[] | EventListener<MembersEventMap[K]>,
     listener?: EventListener<MembersEventMap[K]>,
   ) {
diff --git a/src/Space.ts b/src/Space.ts
index 7a4bebc8..8e8c26d4 100644
--- a/src/Space.ts
+++ b/src/Space.ts
@@ -1,11 +1,6 @@
 import Ably, { Types } from 'ably';
 
-import EventEmitter, {
-  InvalidArgumentError,
-  inspect,
-  type EventKey,
-  type EventListener,
-} from './utilities/EventEmitter.js';
+import EventEmitter, { InvalidArgumentError, inspect, type EventListener } from './utilities/EventEmitter.js';
 import Locations from './Locations.js';
 import Cursors from './Cursors.js';
 import Members from './Members.js';
@@ -184,7 +179,7 @@ class Space extends EventEmitter<SpaceEventMap> {
     return { members };
   }
 
-  subscribe<K extends EventKey<SpaceEventMap>>(
+  subscribe<K extends keyof SpaceEventMap>(
     listenerOrEvents?: K | K[] | EventListener<SpaceEventMap[K]>,
     listener?: EventListener<SpaceEventMap[K]>,
   ) {
@@ -201,7 +196,7 @@ class Space extends EventEmitter<SpaceEventMap> {
     }
   }
 
-  unsubscribe<K extends EventKey<SpaceEventMap>>(
+  unsubscribe<K extends keyof SpaceEventMap>(
     listenerOrEvents?: K | K[] | EventListener<SpaceEventMap[K]>,
     listener?: EventListener<SpaceEventMap[K]>,
   ) {
diff --git a/src/index.ts b/src/index.ts
index 1a7da0ca..f4c1c17c 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -25,6 +25,6 @@ export type {
 
 export { LockAttributes } from './Locks.js';
 
-export type { default as EventEmitter, EventListener, EventKey, EventMap } from './utilities/EventEmitter.js';
+export type { default as EventEmitter, EventListener } from './utilities/EventEmitter.js';
 
 export type { Subset } from './utilities/types.js';
diff --git a/src/utilities/EventEmitter.test.ts b/src/utilities/EventEmitter.test.ts
index 330102ea..8e2a62e6 100644
--- a/src/utilities/EventEmitter.test.ts
+++ b/src/utilities/EventEmitter.test.ts
@@ -174,7 +174,7 @@ describe('EventEmitter', () => {
     });
 
     it('removes a specific listener from multiple events', () => {
-      const eventEmitter = new EventEmitter();
+      const eventEmitter = new EventEmitter<{ myEvent: unknown; myOtherEvent: unknown; myThirdEvent: unknown }>();
       const specificListener = vi.fn();
       eventEmitter['on'](['myEvent', 'myOtherEvent', 'myThirdEvent'], specificListener);
       eventEmitter['off'](['myEvent', 'myOtherEvent'], specificListener);
diff --git a/src/utilities/EventEmitter.ts b/src/utilities/EventEmitter.ts
index f23289a8..4ffa4929 100644
--- a/src/utilities/EventEmitter.ts
+++ b/src/utilities/EventEmitter.ts
@@ -1,6 +1,6 @@
 import { isArray, isFunction, isObject, isString } from './is.js';
 
-function callListener(eventThis: { event: string }, listener: Function, args: unknown[]) {
+function callListener<K>(eventThis: { event: K }, listener: Function, args: unknown[]) {
   try {
     listener.apply(eventThis, args);
   } catch (e) {
@@ -17,14 +17,14 @@ function callListener(eventThis: { event: string }, listener: Function, args: un
  * @param listener the listener callback to remove
  * @param eventFilter (optional) event name instructing the function to only remove listeners for the specified event
  */
-export function removeListener(
-  targetListeners: (Function[] | Record<string, Function[]>)[],
+export function removeListener<T>(
+  targetListeners: (Function[] | Record<keyof T, Function[]>)[],
   listener: Function,
-  eventFilter?: string,
+  eventFilter?: keyof T,
 ) {
-  let listeners: Function[] | Record<string, Function[]>;
+  let listeners: Function[] | Record<keyof T, Function[]>;
   let index: number;
-  let eventName: string;
+  let eventName: keyof T;
 
   for (let targetListenersIndex = 0; targetListenersIndex < targetListeners.length; targetListenersIndex++) {
     listeners = targetListeners[targetListenersIndex];
@@ -64,20 +64,17 @@ export class InvalidArgumentError extends Error {
   }
 }
 
-export type EventMap = Record<string, unknown>;
-// extract all the keys of an event map and use them as a type
-export type EventKey<T extends EventMap> = string & keyof T;
 export type EventListener<T> = (params: T) => void;
 
-export default class EventEmitter<T extends EventMap> {
+export default class EventEmitter<T> {
   /** @internal */
   any: Array<Function>;
   /** @internal */
-  events: Record<string, Function[]>;
+  events: Record<keyof T, Function[]>;
   /** @internal */
   anyOnce: Array<Function>;
   /** @internal */
-  eventsOnce: Record<string, Function[]>;
+  eventsOnce: Record<keyof T, Function[]>;
 
   /**
    * @internal
@@ -94,7 +91,7 @@ export default class EventEmitter<T extends EventMap> {
    * @param listenerOrEvents (optional) the name of the event to listen to or the listener to be called.
    * @param listener (optional) the listener to be called.
    */
-  on<K extends EventKey<T>>(listenerOrEvents?: K | K[] | EventListener<T[K]>, listener?: EventListener<T[K]>): void {
+  on<K extends keyof T>(listenerOrEvents?: K | K[] | EventListener<T[K]>, listener?: EventListener<T[K]>): void {
     // .on(() => {})
     if (isFunction(listenerOrEvents)) {
       this.any.push(listenerOrEvents);
@@ -125,7 +122,7 @@ export default class EventEmitter<T extends EventMap> {
    * the listener is treated as an 'any' listener.
    * @param listener (optional) the listener to remove. If not supplied, all listeners are removed.
    */
-  off<K extends EventKey<T>>(listenerOrEvents?: K | K[] | EventListener<T[K]>, listener?: EventListener<T[K]>): void {
+  off<K extends keyof T>(listenerOrEvents?: K | K[] | EventListener<T[K]>, listener?: EventListener<T[K]>): void {
     // .off()
     // don't use arguments.length === 0 here as don't won't handle
     // cases like .off(undefined) which is a valid call
@@ -180,7 +177,7 @@ export default class EventEmitter<T extends EventMap> {
    * @param event (optional) the name of the event, or none for 'any'
    * @return array of events, or null if none
    */
-  listeners<K extends EventKey<T>>(event: K): Function[] | null {
+  listeners<K extends keyof T>(event: K): Function[] | null {
     if (event) {
       const listeners = [...(this.events[event] ?? [])];
 
@@ -201,7 +198,7 @@ export default class EventEmitter<T extends EventMap> {
    * @param event the event name
    * @param arg the arguments to pass to the listener
    */
-  emit<K extends EventKey<T>>(event: K, arg: T[K]) {
+  emit<K extends keyof T>(event: K, arg: T[K]) {
     const eventThis = { event };
     const listeners: Function[] = [];
 
@@ -235,7 +232,7 @@ export default class EventEmitter<T extends EventMap> {
    * @param listenerOrEvent (optional) the name of the event to listen to
    * @param listener (optional) the listener to be called
    */
-  once<K extends EventKey<T>>(
+  once<K extends keyof T>(
     listenerOrEvent: K | EventListener<T[K]>,
     listener?: EventListener<T[K]>,
   ): void | Promise<any> {
@@ -264,7 +261,12 @@ export default class EventEmitter<T extends EventMap> {
    * @param listener the listener to be called
    * @param listenerArgs
    */
-  whenState(targetState: string, currentState: string, listener: EventListener<T[string]>, ...listenerArgs: unknown[]) {
+  whenState(
+    targetState: keyof T,
+    currentState: keyof T,
+    listener: EventListener<T[keyof T]>,
+    ...listenerArgs: unknown[]
+  ) {
     const eventThis = { event: targetState };
 
     if (typeof targetState !== 'string' || typeof currentState !== 'string') {
diff --git a/src/utilities/is.ts b/src/utilities/is.ts
index 8a6fd0d3..5e3e4435 100644
--- a/src/utilities/is.ts
+++ b/src/utilities/is.ts
@@ -11,7 +11,7 @@ function isFunction(arg: unknown): arg is Function {
   return ['Function', 'AsyncFunction', 'GeneratorFunction', 'Proxy'].includes(typeOf(arg));
 }
 
-function isString(arg: unknown): arg is String {
+function isString(arg: unknown): arg is string {
   return typeOf(arg) === 'String';
 }
 

From b70d185ba6de12294d7198a7fb9c98f756630ce3 Mon Sep 17 00:00:00 2001
From: Lawrence Forooghian <lawrence@forooghian.com>
Date: Wed, 27 Sep 2023 20:52:07 -0300
Subject: [PATCH 08/30] Improve typing of callListener function
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Change `listener`’s type from Function to EventListener, and make it
clearer that an EventListener takes a single argument.
---
 src/utilities/EventEmitter.ts | 27 ++++++++++++---------------
 1 file changed, 12 insertions(+), 15 deletions(-)

diff --git a/src/utilities/EventEmitter.ts b/src/utilities/EventEmitter.ts
index 4ffa4929..c34fae2a 100644
--- a/src/utilities/EventEmitter.ts
+++ b/src/utilities/EventEmitter.ts
@@ -1,8 +1,8 @@
 import { isArray, isFunction, isObject, isString } from './is.js';
 
-function callListener<K>(eventThis: { event: K }, listener: Function, args: unknown[]) {
+function callListener<T, K extends keyof T>(eventThis: { event: K }, listener: EventListener<T[K]>, arg: T[K]) {
   try {
-    listener.apply(eventThis, args);
+    listener.apply(eventThis, [arg]);
   } catch (e) {
     console.error(
       'EventEmitter.emit()',
@@ -64,7 +64,7 @@ export class InvalidArgumentError extends Error {
   }
 }
 
-export type EventListener<T> = (params: T) => void;
+export type EventListener<T> = (param: T) => void;
 
 export default class EventEmitter<T> {
   /** @internal */
@@ -200,7 +200,7 @@ export default class EventEmitter<T> {
    */
   emit<K extends keyof T>(event: K, arg: T[K]) {
     const eventThis = { event };
-    const listeners: Function[] = [];
+    const listeners: EventListener<T[K]>[] = [];
 
     if (this.anyOnce.length > 0) {
       Array.prototype.push.apply(listeners, this.anyOnce);
@@ -223,7 +223,7 @@ export default class EventEmitter<T> {
     }
 
     listeners.forEach(function (listener) {
-      callListener(eventThis, listener, [arg]);
+      callListener(eventThis, listener, arg);
     });
   }
 
@@ -259,13 +259,13 @@ export default class EventEmitter<T> {
    * @param targetState the name of the state event to listen to
    * @param currentState the name of the current state of this object
    * @param listener the listener to be called
-   * @param listenerArgs
+   * @param listenerArg the argument to pass to the listener
    */
-  whenState(
-    targetState: keyof T,
+  whenState<K extends keyof T>(
+    targetState: K,
     currentState: keyof T,
-    listener: EventListener<T[keyof T]>,
-    ...listenerArgs: unknown[]
+    listener: EventListener<T[K]>,
+    listenerArg: T[K],
   ) {
     const eventThis = { event: targetState };
 
@@ -274,14 +274,11 @@ export default class EventEmitter<T> {
     }
     if (typeof listener !== 'function' && Promise) {
       return new Promise((resolve) => {
-        EventEmitter.prototype.whenState.apply(
-          this,
-          [targetState, currentState, resolve].concat(listenerArgs as any[]) as any,
-        );
+        EventEmitter.prototype.whenState.apply(this, [targetState, currentState, resolve, listenerArg]);
       });
     }
     if (targetState === currentState) {
-      callListener(eventThis, listener, listenerArgs);
+      callListener(eventThis, listener, listenerArg);
     } else {
       this.once(targetState, listener);
     }

From 18f1d2bb90b45ec100d03163796a809271430716 Mon Sep 17 00:00:00 2001
From: Lawrence Forooghian <lawrence@forooghian.com>
Date: Thu, 21 Sep 2023 15:26:58 -0300
Subject: [PATCH 09/30] Convert *EventMap types to interfaces

So that I can use {@link} in documentation comments to link to the
documentation of each of their properties.
---
 src/Cursors.ts   | 4 ++--
 src/Locations.ts | 4 ++--
 src/Locks.ts     | 4 ++--
 src/Members.ts   | 4 ++--
 src/Space.ts     | 4 ++--
 5 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/src/Cursors.ts b/src/Cursors.ts
index da9cb764..7786f445 100644
--- a/src/Cursors.ts
+++ b/src/Cursors.ts
@@ -11,9 +11,9 @@ import type { CursorsOptions, CursorUpdate } from './types.js';
 import type { RealtimeMessage } from './utilities/types.js';
 import { ERR_NOT_ENTERED_SPACE } from './Errors.js';
 
-export type CursorsEventMap = {
+export interface CursorsEventMap {
   update: CursorUpdate;
-};
+}
 
 const CURSORS_CHANNEL_TAG = '::$cursors';
 
diff --git a/src/Locations.ts b/src/Locations.ts
index a5118786..9aa10b07 100644
--- a/src/Locations.ts
+++ b/src/Locations.ts
@@ -14,9 +14,9 @@ export namespace LocationsEvents {
   }
 }
 
-export type LocationsEventMap = {
+export interface LocationsEventMap {
   update: LocationsEvents.UpdateEvent;
-};
+}
 
 export default class Locations extends EventEmitter<LocationsEventMap> {
   private lastLocationUpdate: Record<string, PresenceMember['data']['locationUpdate']['id']> = {};
diff --git a/src/Locks.ts b/src/Locks.ts
index 5b646a39..4ba0ac57 100644
--- a/src/Locks.ts
+++ b/src/Locks.ts
@@ -18,9 +18,9 @@ export interface LockOptions {
   attributes: LockAttributes;
 }
 
-export type LocksEventMap = {
+export interface LocksEventMap {
   update: Lock;
-};
+}
 
 export default class Locks extends EventEmitter<LocksEventMap> {
   // locks tracks the local state of locks, which is used to determine whether
diff --git a/src/Members.ts b/src/Members.ts
index f0461f4e..9243debb 100644
--- a/src/Members.ts
+++ b/src/Members.ts
@@ -5,13 +5,13 @@ import type { SpaceMember } from './types.js';
 import type { PresenceMember } from './utilities/types.js';
 import type Space from './Space.js';
 
-export type MembersEventMap = {
+export interface MembersEventMap {
   leave: SpaceMember;
   enter: SpaceMember;
   update: SpaceMember;
   updateProfile: SpaceMember;
   remove: SpaceMember;
-};
+}
 
 class Members extends EventEmitter<MembersEventMap> {
   private lastMemberUpdate: Record<string, PresenceMember['data']['profileUpdate']['id']> = {};
diff --git a/src/Space.ts b/src/Space.ts
index 8e8c26d4..4989abcc 100644
--- a/src/Space.ts
+++ b/src/Space.ts
@@ -30,9 +30,9 @@ export namespace SpaceEvents {
   }
 }
 
-export type SpaceEventMap = {
+export interface SpaceEventMap {
   update: SpaceEvents.UpdateEvent;
-};
+}
 
 class Space extends EventEmitter<SpaceEventMap> {
   private readonly channelName: string;

From 87e1eba4d394ac0b1a8b0cb2c0ecba08de75cdfc Mon Sep 17 00:00:00 2001
From: Lawrence Forooghian <lawrence@forooghian.com>
Date: Tue, 26 Sep 2023 15:21:58 -0300
Subject: [PATCH 10/30] =?UTF-8?q?Split=20LockStatus=E2=80=99s=20allowed=20?=
 =?UTF-8?q?values=20into=20separate=20types?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

So that they can be individually documented.
---
 src/index.ts | 1 +
 src/types.ts | 8 +++++++-
 2 files changed, 8 insertions(+), 1 deletion(-)

diff --git a/src/index.ts b/src/index.ts
index f4c1c17c..ffb2b1b4 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -21,6 +21,7 @@ export type {
   SpaceMember,
   Lock,
   LockStatus,
+  LockStatuses,
 } from './types.js';
 
 export { LockAttributes } from './Locks.js';
diff --git a/src/types.ts b/src/types.ts
index 9641b53c..96a16ba7 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -39,7 +39,13 @@ export interface SpaceMember {
   };
 }
 
-export type LockStatus = 'pending' | 'locked' | 'unlocked';
+export namespace LockStatuses {
+  export type Pending = 'pending';
+  export type Locked = 'locked';
+  export type Unlocked = 'unlocked';
+}
+
+export type LockStatus = LockStatuses.Pending | LockStatuses.Locked | LockStatuses.Unlocked;
 
 export type Lock = {
   id: string;

From f5a8b6ea082b2a6d3fe01d9f517402025e2ed22f Mon Sep 17 00:00:00 2001
From: Lawrence Forooghian <lawrence@forooghian.com>
Date: Wed, 27 Sep 2023 14:50:02 -0300
Subject: [PATCH 11/30] Create overload signatures for event-related methods
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The subscribe, unsubscribe, … etc methods are easier to understand (and
easier to document) when thought of as two variants: one which accepts
one or more event names, and one which doesn’t. So create these overload
signatures.
---
 src/Cursors.ts                | 10 ++++++++
 src/Locations.ts              | 10 ++++++++
 src/Locks.ts                  |  4 +++
 src/Members.ts                | 10 ++++++++
 src/Space.ts                  |  4 +++
 src/utilities/EventEmitter.ts | 46 ++++++++++++++++++++++++++++++++---
 6 files changed, 80 insertions(+), 4 deletions(-)

diff --git a/src/Cursors.ts b/src/Cursors.ts
index 7786f445..0b1f5b59 100644
--- a/src/Cursors.ts
+++ b/src/Cursors.ts
@@ -100,6 +100,11 @@ export default class Cursors extends EventEmitter<CursorsEventMap> {
     );
   };
 
+  subscribe<K extends keyof CursorsEventMap>(
+    eventOrEvents: K | K[],
+    listener?: EventListener<CursorsEventMap[K]>,
+  ): void;
+  subscribe(listener?: EventListener<CursorsEventMap[keyof CursorsEventMap]>): void;
   subscribe<K extends keyof CursorsEventMap>(
     listenerOrEvents?: K | K[] | EventListener<CursorsEventMap[K]>,
     listener?: EventListener<CursorsEventMap[K]>,
@@ -125,6 +130,11 @@ export default class Cursors extends EventEmitter<CursorsEventMap> {
     }
   }
 
+  unsubscribe<K extends keyof CursorsEventMap>(
+    eventOrEvents: K | K[],
+    listener?: EventListener<CursorsEventMap[K]>,
+  ): void;
+  unsubscribe(listener?: EventListener<CursorsEventMap[keyof CursorsEventMap]>): void;
   unsubscribe<K extends keyof CursorsEventMap>(
     listenerOrEvents?: K | K[] | EventListener<CursorsEventMap[K]>,
     listener?: EventListener<CursorsEventMap[K]>,
diff --git a/src/Locations.ts b/src/Locations.ts
index 9aa10b07..1a8cc804 100644
--- a/src/Locations.ts
+++ b/src/Locations.ts
@@ -66,6 +66,11 @@ export default class Locations extends EventEmitter<LocationsEventMap> {
     await this.presenceUpdate(update.updateLocation(location));
   }
 
+  subscribe<K extends keyof LocationsEventMap>(
+    eventOrEvents: K | K[],
+    listener?: EventListener<LocationsEventMap[K]>,
+  ): void;
+  subscribe(listener?: EventListener<LocationsEventMap[keyof LocationsEventMap]>): void;
   subscribe<K extends keyof LocationsEventMap>(
     listenerOrEvents?: K | K[] | EventListener<LocationsEventMap[K]>,
     listener?: EventListener<LocationsEventMap[K]>,
@@ -83,6 +88,11 @@ export default class Locations extends EventEmitter<LocationsEventMap> {
     }
   }
 
+  unsubscribe<K extends keyof LocationsEventMap>(
+    eventOrEvents: K | K[],
+    listener?: EventListener<LocationsEventMap[K]>,
+  ): void;
+  unsubscribe(listener?: EventListener<LocationsEventMap[keyof LocationsEventMap]>): void;
   unsubscribe<K extends keyof LocationsEventMap>(
     listenerOrEvents?: K | K[] | EventListener<LocationsEventMap[K]>,
     listener?: EventListener<LocationsEventMap[K]>,
diff --git a/src/Locks.ts b/src/Locks.ts
index 4ba0ac57..1ccd831e 100644
--- a/src/Locks.ts
+++ b/src/Locks.ts
@@ -131,6 +131,8 @@ export default class Locks extends EventEmitter<LocksEventMap> {
     this.deleteLock(id, self.connectionId);
   }
 
+  subscribe<K extends keyof LocksEventMap>(eventOrEvents: K | K[], listener?: EventListener<LocksEventMap[K]>): void;
+  subscribe(listener?: EventListener<LocksEventMap[keyof LocksEventMap]>): void;
   subscribe<K extends keyof LocksEventMap>(
     listenerOrEvents?: K | K[] | EventListener<LocksEventMap[K]>,
     listener?: EventListener<LocksEventMap[K]>,
@@ -148,6 +150,8 @@ export default class Locks extends EventEmitter<LocksEventMap> {
     }
   }
 
+  unsubscribe<K extends keyof LocksEventMap>(eventOrEvents: K | K[], listener?: EventListener<LocksEventMap[K]>): void;
+  unsubscribe(listener?: EventListener<LocksEventMap[keyof LocksEventMap]>): void;
   unsubscribe<K extends keyof LocksEventMap>(
     listenerOrEvents?: K | K[] | EventListener<LocksEventMap[K]>,
     listener?: EventListener<LocksEventMap[K]>,
diff --git a/src/Members.ts b/src/Members.ts
index 9243debb..16543aa7 100644
--- a/src/Members.ts
+++ b/src/Members.ts
@@ -66,6 +66,11 @@ class Members extends EventEmitter<MembersEventMap> {
     return members.filter((m) => m.connectionId !== this.space.connectionId);
   }
 
+  subscribe<K extends keyof MembersEventMap>(
+    eventOrEvents: K | K[],
+    listener?: EventListener<MembersEventMap[K]>,
+  ): void;
+  subscribe(listener?: EventListener<MembersEventMap[keyof MembersEventMap]>): void;
   subscribe<K extends keyof MembersEventMap>(
     listenerOrEvents?: K | K[] | EventListener<MembersEventMap[K]>,
     listener?: EventListener<MembersEventMap[K]>,
@@ -83,6 +88,11 @@ class Members extends EventEmitter<MembersEventMap> {
     }
   }
 
+  unsubscribe<K extends keyof MembersEventMap>(
+    eventOrEvents: K | K[],
+    listener?: EventListener<MembersEventMap[K]>,
+  ): void;
+  unsubscribe(listener?: EventListener<MembersEventMap[keyof MembersEventMap]>): void;
   unsubscribe<K extends keyof MembersEventMap>(
     listenerOrEvents?: K | K[] | EventListener<MembersEventMap[K]>,
     listener?: EventListener<MembersEventMap[K]>,
diff --git a/src/Space.ts b/src/Space.ts
index 4989abcc..da22853d 100644
--- a/src/Space.ts
+++ b/src/Space.ts
@@ -179,6 +179,8 @@ class Space extends EventEmitter<SpaceEventMap> {
     return { members };
   }
 
+  subscribe<K extends keyof SpaceEventMap>(eventOrEvents: K | K[], listener?: EventListener<SpaceEventMap[K]>): void;
+  subscribe(listener?: EventListener<SpaceEventMap[keyof SpaceEventMap]>): void;
   subscribe<K extends keyof SpaceEventMap>(
     listenerOrEvents?: K | K[] | EventListener<SpaceEventMap[K]>,
     listener?: EventListener<SpaceEventMap[K]>,
@@ -196,6 +198,8 @@ class Space extends EventEmitter<SpaceEventMap> {
     }
   }
 
+  unsubscribe<K extends keyof SpaceEventMap>(eventOrEvents: K | K[], listener?: EventListener<SpaceEventMap[K]>): void;
+  unsubscribe(listener?: EventListener<SpaceEventMap[keyof SpaceEventMap]>): void;
   unsubscribe<K extends keyof SpaceEventMap>(
     listenerOrEvents?: K | K[] | EventListener<SpaceEventMap[K]>,
     listener?: EventListener<SpaceEventMap[K]>,
diff --git a/src/utilities/EventEmitter.ts b/src/utilities/EventEmitter.ts
index c34fae2a..b7145ab7 100644
--- a/src/utilities/EventEmitter.ts
+++ b/src/utilities/EventEmitter.ts
@@ -87,10 +87,22 @@ export default class EventEmitter<T> {
   }
 
   /**
+   * {@label WITH_EVENTS}
    * Add an event listener
-   * @param listenerOrEvents (optional) the name of the event to listen to or the listener to be called.
+   * @param eventOrEvents the name of the event to listen to or the listener to be called.
    * @param listener (optional) the listener to be called.
    */
+  on<K extends keyof T>(eventOrEvents?: K | K[], listener?: EventListener<T[K]>): void;
+  /**
+   * Behaves the same as { @link on:WITH_EVENTS | the overload which accepts one or more event names }, but listens to _all_ events.
+   * @param listener (optional) the listener to be called.
+   */
+  on(listener?: EventListener<T[keyof T]>): void;
+  /**
+   * @internal
+   * We add the implementation signature as an overload signature (but mark it as internal so that it does not appear in documentation) so that it can be called by subclasses.
+   */
+  on<K extends keyof T>(listenerOrEvents?: K | K[] | EventListener<T[K]>, listener?: EventListener<T[K]>): void;
   on<K extends keyof T>(listenerOrEvents?: K | K[] | EventListener<T[K]>, listener?: EventListener<T[K]>): void {
     // .on(() => {})
     if (isFunction(listenerOrEvents)) {
@@ -117,11 +129,22 @@ export default class EventEmitter<T> {
   }
 
   /**
+   * {@label WITH_EVENTS}
    * Remove one or more event listeners
-   * @param listenerOrEvents (optional) the name of the event whose listener is to be removed. If not supplied,
-   * the listener is treated as an 'any' listener.
+   * @param eventOrEvents the name of the event whose listener is to be removed.
    * @param listener (optional) the listener to remove. If not supplied, all listeners are removed.
    */
+  off<K extends keyof T>(eventOrEvents?: K | K[], listener?: EventListener<T[K]>): void;
+  /**
+   * Behaves the same as { @link off:WITH_EVENTS | the overload which accepts one or more event names }, but removes the listener from _all_ events.
+   * @param listener (optional) the listener to remove. If not supplied, all listeners are removed.
+   */
+  off(listener?: EventListener<T[keyof T]>): void;
+  /**
+   * @internal
+   * We add the implementation signature as an overload signature (but mark it as internal so that it does not appear in documentation) so that it can be called by subclasses.
+   */
+  off<K extends keyof T>(listenerOrEvents?: K | K[] | EventListener<T[K]>, listener?: EventListener<T[K]>): void;
   off<K extends keyof T>(listenerOrEvents?: K | K[] | EventListener<T[K]>, listener?: EventListener<T[K]>): void {
     // .off()
     // don't use arguments.length === 0 here as don't won't handle
@@ -228,10 +251,25 @@ export default class EventEmitter<T> {
   }
 
   /**
+   * {@label WITH_EVENTS}
    * Listen for a single occurrence of an event
-   * @param listenerOrEvent (optional) the name of the event to listen to
+   * @param event the name of the event to listen to
    * @param listener (optional) the listener to be called
    */
+  once<K extends keyof T>(event: K, listener?: EventListener<T[K]>): void | Promise<any>;
+  /**
+   * Behaves the same as { @link once:WITH_EVENTS | the overload which accepts one or more event names }, but listens for _all_ events.
+   * @param listener (optional) the listener to be called
+   */
+  once(listener?: EventListener<T[keyof T]>): void | Promise<any>;
+  /**
+   * @internal
+   * We add the implementation signature as an overload signature (but mark it as internal so that it does not appear in documentation) so that it can be called by subclasses.
+   */
+  once<K extends keyof T>(
+    listenerOrEvent: K | EventListener<T[K]>,
+    listener?: EventListener<T[K]>,
+  ): void | Promise<any>;
   once<K extends keyof T>(
     listenerOrEvent: K | EventListener<T[K]>,
     listener?: EventListener<T[K]>,

From 02f8f04619804d8579b2262e9842574416248aa8 Mon Sep 17 00:00:00 2001
From: Lawrence Forooghian <lawrence@forooghian.com>
Date: Wed, 27 Sep 2023 22:45:10 -0300
Subject: [PATCH 12/30] Add `this` type parameter to EventListener

Make it clear, via the type system, that a listener can access the name
of the emitted event via the `this` variable.
---
 src/Cursors.ts                | 16 ++++++++--------
 src/Locations.ts              | 16 ++++++++--------
 src/Locks.ts                  | 16 ++++++++--------
 src/Members.ts                | 16 ++++++++--------
 src/Space.ts                  | 16 ++++++++--------
 src/utilities/EventEmitter.ts | 36 +++++++++++++++++------------------
 6 files changed, 58 insertions(+), 58 deletions(-)

diff --git a/src/Cursors.ts b/src/Cursors.ts
index 0b1f5b59..936ee370 100644
--- a/src/Cursors.ts
+++ b/src/Cursors.ts
@@ -102,12 +102,12 @@ export default class Cursors extends EventEmitter<CursorsEventMap> {
 
   subscribe<K extends keyof CursorsEventMap>(
     eventOrEvents: K | K[],
-    listener?: EventListener<CursorsEventMap[K]>,
+    listener?: EventListener<CursorsEventMap, K>,
   ): void;
-  subscribe(listener?: EventListener<CursorsEventMap[keyof CursorsEventMap]>): void;
+  subscribe(listener?: EventListener<CursorsEventMap, keyof CursorsEventMap>): void;
   subscribe<K extends keyof CursorsEventMap>(
-    listenerOrEvents?: K | K[] | EventListener<CursorsEventMap[K]>,
-    listener?: EventListener<CursorsEventMap[K]>,
+    listenerOrEvents?: K | K[] | EventListener<CursorsEventMap, K>,
+    listener?: EventListener<CursorsEventMap, K>,
   ) {
     try {
       super.on(listenerOrEvents, listener);
@@ -132,12 +132,12 @@ export default class Cursors extends EventEmitter<CursorsEventMap> {
 
   unsubscribe<K extends keyof CursorsEventMap>(
     eventOrEvents: K | K[],
-    listener?: EventListener<CursorsEventMap[K]>,
+    listener?: EventListener<CursorsEventMap, K>,
   ): void;
-  unsubscribe(listener?: EventListener<CursorsEventMap[keyof CursorsEventMap]>): void;
+  unsubscribe(listener?: EventListener<CursorsEventMap, keyof CursorsEventMap>): void;
   unsubscribe<K extends keyof CursorsEventMap>(
-    listenerOrEvents?: K | K[] | EventListener<CursorsEventMap[K]>,
-    listener?: EventListener<CursorsEventMap[K]>,
+    listenerOrEvents?: K | K[] | EventListener<CursorsEventMap, K>,
+    listener?: EventListener<CursorsEventMap, K>,
   ) {
     try {
       super.off(listenerOrEvents, listener);
diff --git a/src/Locations.ts b/src/Locations.ts
index 1a8cc804..ddf78885 100644
--- a/src/Locations.ts
+++ b/src/Locations.ts
@@ -68,12 +68,12 @@ export default class Locations extends EventEmitter<LocationsEventMap> {
 
   subscribe<K extends keyof LocationsEventMap>(
     eventOrEvents: K | K[],
-    listener?: EventListener<LocationsEventMap[K]>,
+    listener?: EventListener<LocationsEventMap, K>,
   ): void;
-  subscribe(listener?: EventListener<LocationsEventMap[keyof LocationsEventMap]>): void;
+  subscribe(listener?: EventListener<LocationsEventMap, keyof LocationsEventMap>): void;
   subscribe<K extends keyof LocationsEventMap>(
-    listenerOrEvents?: K | K[] | EventListener<LocationsEventMap[K]>,
-    listener?: EventListener<LocationsEventMap[K]>,
+    listenerOrEvents?: K | K[] | EventListener<LocationsEventMap, K>,
+    listener?: EventListener<LocationsEventMap, K>,
   ) {
     try {
       super.on(listenerOrEvents, listener);
@@ -90,12 +90,12 @@ export default class Locations extends EventEmitter<LocationsEventMap> {
 
   unsubscribe<K extends keyof LocationsEventMap>(
     eventOrEvents: K | K[],
-    listener?: EventListener<LocationsEventMap[K]>,
+    listener?: EventListener<LocationsEventMap, K>,
   ): void;
-  unsubscribe(listener?: EventListener<LocationsEventMap[keyof LocationsEventMap]>): void;
+  unsubscribe(listener?: EventListener<LocationsEventMap, keyof LocationsEventMap>): void;
   unsubscribe<K extends keyof LocationsEventMap>(
-    listenerOrEvents?: K | K[] | EventListener<LocationsEventMap[K]>,
-    listener?: EventListener<LocationsEventMap[K]>,
+    listenerOrEvents?: K | K[] | EventListener<LocationsEventMap, K>,
+    listener?: EventListener<LocationsEventMap, K>,
   ) {
     try {
       super.off(listenerOrEvents, listener);
diff --git a/src/Locks.ts b/src/Locks.ts
index 1ccd831e..309daffb 100644
--- a/src/Locks.ts
+++ b/src/Locks.ts
@@ -131,11 +131,11 @@ export default class Locks extends EventEmitter<LocksEventMap> {
     this.deleteLock(id, self.connectionId);
   }
 
-  subscribe<K extends keyof LocksEventMap>(eventOrEvents: K | K[], listener?: EventListener<LocksEventMap[K]>): void;
-  subscribe(listener?: EventListener<LocksEventMap[keyof LocksEventMap]>): void;
+  subscribe<K extends keyof LocksEventMap>(eventOrEvents: K | K[], listener?: EventListener<LocksEventMap, K>): void;
+  subscribe(listener?: EventListener<LocksEventMap, keyof LocksEventMap>): void;
   subscribe<K extends keyof LocksEventMap>(
-    listenerOrEvents?: K | K[] | EventListener<LocksEventMap[K]>,
-    listener?: EventListener<LocksEventMap[K]>,
+    listenerOrEvents?: K | K[] | EventListener<LocksEventMap, K>,
+    listener?: EventListener<LocksEventMap, K>,
   ) {
     try {
       super.on(listenerOrEvents, listener);
@@ -150,11 +150,11 @@ export default class Locks extends EventEmitter<LocksEventMap> {
     }
   }
 
-  unsubscribe<K extends keyof LocksEventMap>(eventOrEvents: K | K[], listener?: EventListener<LocksEventMap[K]>): void;
-  unsubscribe(listener?: EventListener<LocksEventMap[keyof LocksEventMap]>): void;
+  unsubscribe<K extends keyof LocksEventMap>(eventOrEvents: K | K[], listener?: EventListener<LocksEventMap, K>): void;
+  unsubscribe(listener?: EventListener<LocksEventMap, keyof LocksEventMap>): void;
   unsubscribe<K extends keyof LocksEventMap>(
-    listenerOrEvents?: K | K[] | EventListener<LocksEventMap[K]>,
-    listener?: EventListener<LocksEventMap[K]>,
+    listenerOrEvents?: K | K[] | EventListener<LocksEventMap, K>,
+    listener?: EventListener<LocksEventMap, K>,
   ) {
     try {
       super.off(listenerOrEvents, listener);
diff --git a/src/Members.ts b/src/Members.ts
index 16543aa7..b058fc4b 100644
--- a/src/Members.ts
+++ b/src/Members.ts
@@ -68,12 +68,12 @@ class Members extends EventEmitter<MembersEventMap> {
 
   subscribe<K extends keyof MembersEventMap>(
     eventOrEvents: K | K[],
-    listener?: EventListener<MembersEventMap[K]>,
+    listener?: EventListener<MembersEventMap, K>,
   ): void;
-  subscribe(listener?: EventListener<MembersEventMap[keyof MembersEventMap]>): void;
+  subscribe(listener?: EventListener<MembersEventMap, keyof MembersEventMap>): void;
   subscribe<K extends keyof MembersEventMap>(
-    listenerOrEvents?: K | K[] | EventListener<MembersEventMap[K]>,
-    listener?: EventListener<MembersEventMap[K]>,
+    listenerOrEvents?: K | K[] | EventListener<MembersEventMap, K>,
+    listener?: EventListener<MembersEventMap, K>,
   ) {
     try {
       super.on(listenerOrEvents, listener);
@@ -90,12 +90,12 @@ class Members extends EventEmitter<MembersEventMap> {
 
   unsubscribe<K extends keyof MembersEventMap>(
     eventOrEvents: K | K[],
-    listener?: EventListener<MembersEventMap[K]>,
+    listener?: EventListener<MembersEventMap, K>,
   ): void;
-  unsubscribe(listener?: EventListener<MembersEventMap[keyof MembersEventMap]>): void;
+  unsubscribe(listener?: EventListener<MembersEventMap, keyof MembersEventMap>): void;
   unsubscribe<K extends keyof MembersEventMap>(
-    listenerOrEvents?: K | K[] | EventListener<MembersEventMap[K]>,
-    listener?: EventListener<MembersEventMap[K]>,
+    listenerOrEvents?: K | K[] | EventListener<MembersEventMap, K>,
+    listener?: EventListener<MembersEventMap, K>,
   ) {
     try {
       super.off(listenerOrEvents, listener);
diff --git a/src/Space.ts b/src/Space.ts
index da22853d..dfba8a16 100644
--- a/src/Space.ts
+++ b/src/Space.ts
@@ -179,11 +179,11 @@ class Space extends EventEmitter<SpaceEventMap> {
     return { members };
   }
 
-  subscribe<K extends keyof SpaceEventMap>(eventOrEvents: K | K[], listener?: EventListener<SpaceEventMap[K]>): void;
-  subscribe(listener?: EventListener<SpaceEventMap[keyof SpaceEventMap]>): void;
+  subscribe<K extends keyof SpaceEventMap>(eventOrEvents: K | K[], listener?: EventListener<SpaceEventMap, K>): void;
+  subscribe(listener?: EventListener<SpaceEventMap, keyof SpaceEventMap>): void;
   subscribe<K extends keyof SpaceEventMap>(
-    listenerOrEvents?: K | K[] | EventListener<SpaceEventMap[K]>,
-    listener?: EventListener<SpaceEventMap[K]>,
+    listenerOrEvents?: K | K[] | EventListener<SpaceEventMap, K>,
+    listener?: EventListener<SpaceEventMap, K>,
   ) {
     try {
       super.on(listenerOrEvents, listener);
@@ -198,11 +198,11 @@ class Space extends EventEmitter<SpaceEventMap> {
     }
   }
 
-  unsubscribe<K extends keyof SpaceEventMap>(eventOrEvents: K | K[], listener?: EventListener<SpaceEventMap[K]>): void;
-  unsubscribe(listener?: EventListener<SpaceEventMap[keyof SpaceEventMap]>): void;
+  unsubscribe<K extends keyof SpaceEventMap>(eventOrEvents: K | K[], listener?: EventListener<SpaceEventMap, K>): void;
+  unsubscribe(listener?: EventListener<SpaceEventMap, keyof SpaceEventMap>): void;
   unsubscribe<K extends keyof SpaceEventMap>(
-    listenerOrEvents?: K | K[] | EventListener<SpaceEventMap[K]>,
-    listener?: EventListener<SpaceEventMap[K]>,
+    listenerOrEvents?: K | K[] | EventListener<SpaceEventMap, K>,
+    listener?: EventListener<SpaceEventMap, K>,
   ) {
     try {
       super.off(listenerOrEvents, listener);
diff --git a/src/utilities/EventEmitter.ts b/src/utilities/EventEmitter.ts
index b7145ab7..ce1139c1 100644
--- a/src/utilities/EventEmitter.ts
+++ b/src/utilities/EventEmitter.ts
@@ -1,6 +1,6 @@
 import { isArray, isFunction, isObject, isString } from './is.js';
 
-function callListener<T, K extends keyof T>(eventThis: { event: K }, listener: EventListener<T[K]>, arg: T[K]) {
+function callListener<T, K extends keyof T>(eventThis: { event: K }, listener: EventListener<T, K>, arg: T[K]) {
   try {
     listener.apply(eventThis, [arg]);
   } catch (e) {
@@ -64,7 +64,7 @@ export class InvalidArgumentError extends Error {
   }
 }
 
-export type EventListener<T> = (param: T) => void;
+export type EventListener<T, K extends keyof T> = (this: { event: K }, param: T[K]) => void;
 
 export default class EventEmitter<T> {
   /** @internal */
@@ -92,18 +92,18 @@ export default class EventEmitter<T> {
    * @param eventOrEvents the name of the event to listen to or the listener to be called.
    * @param listener (optional) the listener to be called.
    */
-  on<K extends keyof T>(eventOrEvents?: K | K[], listener?: EventListener<T[K]>): void;
+  on<K extends keyof T>(eventOrEvents?: K | K[], listener?: EventListener<T, K>): void;
   /**
    * Behaves the same as { @link on:WITH_EVENTS | the overload which accepts one or more event names }, but listens to _all_ events.
    * @param listener (optional) the listener to be called.
    */
-  on(listener?: EventListener<T[keyof T]>): void;
+  on(listener?: EventListener<T, keyof T>): void;
   /**
    * @internal
    * We add the implementation signature as an overload signature (but mark it as internal so that it does not appear in documentation) so that it can be called by subclasses.
    */
-  on<K extends keyof T>(listenerOrEvents?: K | K[] | EventListener<T[K]>, listener?: EventListener<T[K]>): void;
-  on<K extends keyof T>(listenerOrEvents?: K | K[] | EventListener<T[K]>, listener?: EventListener<T[K]>): void {
+  on<K extends keyof T>(listenerOrEvents?: K | K[] | EventListener<T, K>, listener?: EventListener<T, K>): void;
+  on<K extends keyof T>(listenerOrEvents?: K | K[] | EventListener<T, K>, listener?: EventListener<T, K>): void {
     // .on(() => {})
     if (isFunction(listenerOrEvents)) {
       this.any.push(listenerOrEvents);
@@ -134,18 +134,18 @@ export default class EventEmitter<T> {
    * @param eventOrEvents the name of the event whose listener is to be removed.
    * @param listener (optional) the listener to remove. If not supplied, all listeners are removed.
    */
-  off<K extends keyof T>(eventOrEvents?: K | K[], listener?: EventListener<T[K]>): void;
+  off<K extends keyof T>(eventOrEvents?: K | K[], listener?: EventListener<T, K>): void;
   /**
    * Behaves the same as { @link off:WITH_EVENTS | the overload which accepts one or more event names }, but removes the listener from _all_ events.
    * @param listener (optional) the listener to remove. If not supplied, all listeners are removed.
    */
-  off(listener?: EventListener<T[keyof T]>): void;
+  off(listener?: EventListener<T, keyof T>): void;
   /**
    * @internal
    * We add the implementation signature as an overload signature (but mark it as internal so that it does not appear in documentation) so that it can be called by subclasses.
    */
-  off<K extends keyof T>(listenerOrEvents?: K | K[] | EventListener<T[K]>, listener?: EventListener<T[K]>): void;
-  off<K extends keyof T>(listenerOrEvents?: K | K[] | EventListener<T[K]>, listener?: EventListener<T[K]>): void {
+  off<K extends keyof T>(listenerOrEvents?: K | K[] | EventListener<T, K>, listener?: EventListener<T, K>): void;
+  off<K extends keyof T>(listenerOrEvents?: K | K[] | EventListener<T, K>, listener?: EventListener<T, K>): void {
     // .off()
     // don't use arguments.length === 0 here as don't won't handle
     // cases like .off(undefined) which is a valid call
@@ -223,7 +223,7 @@ export default class EventEmitter<T> {
    */
   emit<K extends keyof T>(event: K, arg: T[K]) {
     const eventThis = { event };
-    const listeners: EventListener<T[K]>[] = [];
+    const listeners: EventListener<T, K>[] = [];
 
     if (this.anyOnce.length > 0) {
       Array.prototype.push.apply(listeners, this.anyOnce);
@@ -256,23 +256,23 @@ export default class EventEmitter<T> {
    * @param event the name of the event to listen to
    * @param listener (optional) the listener to be called
    */
-  once<K extends keyof T>(event: K, listener?: EventListener<T[K]>): void | Promise<any>;
+  once<K extends keyof T>(event: K, listener?: EventListener<T, K>): void | Promise<any>;
   /**
    * Behaves the same as { @link once:WITH_EVENTS | the overload which accepts one or more event names }, but listens for _all_ events.
    * @param listener (optional) the listener to be called
    */
-  once(listener?: EventListener<T[keyof T]>): void | Promise<any>;
+  once(listener?: EventListener<T, keyof T>): void | Promise<any>;
   /**
    * @internal
    * We add the implementation signature as an overload signature (but mark it as internal so that it does not appear in documentation) so that it can be called by subclasses.
    */
   once<K extends keyof T>(
-    listenerOrEvent: K | EventListener<T[K]>,
-    listener?: EventListener<T[K]>,
+    listenerOrEvent: K | EventListener<T, K>,
+    listener?: EventListener<T, K>,
   ): void | Promise<any>;
   once<K extends keyof T>(
-    listenerOrEvent: K | EventListener<T[K]>,
-    listener?: EventListener<T[K]>,
+    listenerOrEvent: K | EventListener<T, K>,
+    listener?: EventListener<T, K>,
   ): void | Promise<any> {
     // .once("eventName", () => {})
     if (isString(listenerOrEvent) && isFunction(listener)) {
@@ -302,7 +302,7 @@ export default class EventEmitter<T> {
   whenState<K extends keyof T>(
     targetState: K,
     currentState: keyof T,
-    listener: EventListener<T[K]>,
+    listener: EventListener<T, K>,
     listenerArg: T[K],
   ) {
     const eventThis = { event: targetState };

From beb605ca6d136763337b9cb9ea619af32a6b352c Mon Sep 17 00:00:00 2001
From: Lawrence Forooghian <lawrence@forooghian.com>
Date: Thu, 28 Sep 2023 13:03:47 -0300
Subject: [PATCH 13/30] Remove unnecessary use of isFunction
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The type system tells us that if `listener` is truthy then it is a
function. Assuming that we trust the type system (e.g. assuming that we
aren’t trying to catch incorrect usage by non-TypeScript users, and in
general I see little evidence that we are trying to) then these
isFunction checks are unnecessary.
---
 src/utilities/EventEmitter.ts | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/utilities/EventEmitter.ts b/src/utilities/EventEmitter.ts
index ce1139c1..b6a3d813 100644
--- a/src/utilities/EventEmitter.ts
+++ b/src/utilities/EventEmitter.ts
@@ -164,7 +164,7 @@ export default class EventEmitter<T> {
     }
 
     // .off("eventName", () => {})
-    if (isString(listenerOrEvents) && isFunction(listener)) {
+    if (isString(listenerOrEvents) && listener) {
       removeListener([this.events, this.eventsOnce], listener, listenerOrEvents);
       return;
     }
@@ -177,7 +177,7 @@ export default class EventEmitter<T> {
     }
 
     // .off(["eventName"], () => {})
-    if (isArray(listenerOrEvents) && isFunction(listener)) {
+    if (isArray(listenerOrEvents) && listener) {
       listenerOrEvents.forEach((eventName) => {
         this.off(eventName, listener);
       });
@@ -275,7 +275,7 @@ export default class EventEmitter<T> {
     listener?: EventListener<T, K>,
   ): void | Promise<any> {
     // .once("eventName", () => {})
-    if (isString(listenerOrEvent) && isFunction(listener)) {
+    if (isString(listenerOrEvent) && listener) {
       const listeners = this.eventsOnce[listenerOrEvent] || (this.eventsOnce[listenerOrEvent] = []);
       listeners.push(listener);
       return;

From 7d9e2170351696bfbf6e90fc698407655fdcf0ec Mon Sep 17 00:00:00 2001
From: Lawrence Forooghian <lawrence@forooghian.com>
Date: Wed, 20 Sep 2023 14:26:38 -0300
Subject: [PATCH 14/30] (WIP) Add notes on class-definitions stuff that's
 missing in codebase
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

I don’t know what I’ll do with this information yet.
---
 docs/class-definitions.md | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/docs/class-definitions.md b/docs/class-definitions.md
index dc9069ff..713379e3 100644
--- a/docs/class-definitions.md
+++ b/docs/class-definitions.md
@@ -327,6 +327,8 @@ The most recent event emitted by [presence](https://ably.com/docs/presence-occup
 
 #### PresenceEvent
 
+TODO This type doesn’t exist in the codebase; it's defined inline in SpaceMember
+
 ```ts
 type PresenceEvent = {
   name: 'enter' | 'leave' | 'update' | 'present';
@@ -416,6 +418,8 @@ const otherLocations = await space.locations.getOthers()
 
 #### Location
 
+TODO this type doesn’t exist in the codebase; `unknown` is used
+
 Represents a location in an application.
 
 ```ts
@@ -424,6 +428,8 @@ type Location = string | Record<string, unknown> | null;
 
 #### LocationUpdate
 
+TODO this type doesn’t exist in the codebase; it’s defined inline in LocationEventMap
+
 Represents a change between locations for a given [`SpaceMember`](#spacemember).
 
 ```ts

From eb3f1b3c704745caf3b7744239f41a55663f6ce5 Mon Sep 17 00:00:00 2001
From: Lawrence Forooghian <lawrence@forooghian.com>
Date: Mon, 18 Sep 2023 15:51:25 -0300
Subject: [PATCH 15/30] Add website documentation as TSDoc comments

Copied all relevant-seeming documentation from website (at commit
5f9e999) to roughly appropriate places in code.

Done:

- avatar.textile
- cursors.textile
- locations.textile
- locking.textile
- space.textile

Skipped:

- setup.textile
- index.textile
---
 src/Cursors.ts   | 232 +++++++++++++++++++++++++++++++++++++++
 src/Locations.ts | 206 ++++++++++++++++++++++++++++++++++
 src/Locks.ts     | 278 ++++++++++++++++++++++++++++++++++++++++++++++
 src/Members.ts   | 279 +++++++++++++++++++++++++++++++++++++++++++++++
 src/Space.ts     | 191 ++++++++++++++++++++++++++++++++
 src/Spaces.ts    |  92 ++++++++++++++++
 6 files changed, 1278 insertions(+)

diff --git a/src/Cursors.ts b/src/Cursors.ts
index 936ee370..ab300c90 100644
--- a/src/Cursors.ts
+++ b/src/Cursors.ts
@@ -17,6 +17,37 @@ export interface CursorsEventMap {
 
 const CURSORS_CHANNEL_TAG = '::$cursors';
 
+/**
+ * > **Documentation source**
+ * >
+ * > The following documentation is copied from the [Spaces documentation website](https://ably.com/docs/spaces).
+ * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/content/spaces/cursors.textile?plain=1#L9-L17) -->
+ * The live cursors feature enables you to track the cursors of members within a space in realtime.
+ *
+ * Cursor events are emitted whenever a member moves their mouse within a space. In order to optimize the efficiency and frequency of updates, cursor position events are automatically batched. The batching interval may be customized in order to further optimize for increased performance versus the number of events published.
+ *
+ * Live cursor updates are not available as part of the "space state":/spaces/space#subscribe and must be subscribed to using "@space.cursors.subscribe()@":#subscribe.
+ *
+ * <aside data-type='important'>
+ * <p>Live cursors are a great way of providing contextual awareness as to what members are looking at within an application. However, too many cursors moving across a page can often be a distraction rather than an enhancement. As such, Ably recommends a maximum of 20 members simultaneously streaming their cursors in a space at any one time for an optimal end-user experience.</p>
+ * </aside>
+ * <!-- END WEBSITE DOCUMENTATION -->
+ *
+ * > **Documentation source**
+ * >
+ * > The following documentation is copied from the [Spaces documentation website](https://ably.com/docs/spaces).
+ * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/content/spaces/cursors.textile?plain=1#L254-L262) -->
+ * h2(#foundations). Live cursor 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.
+ *
+ * Live cursors build upon the functionality of the Pub/Sub Channels "presence":/presence-occupancy/presence feature.
+ *
+ * Due to the high frequency at which updates are streamed for cursor movements, live cursors utilizes its own "channel":/channels. The other features of the Spaces SDK, such as avatar stacks, member locations and component locking all share a single channel. For this same reason, cursor position updates are not included in the "space state":/spaces/space and may only be subscribed to on the @cursors@ namespace.
+ *
+ * The channel is only created when a member calls @space.cursors.set()@. The live cursors channel object can be accessed through @space.cursors.channel@. To monitor the "underlying state of the cursors channel":/channels#states, the channel object can be accessed through @space.cursors.channel@.
+ * <!-- END WEBSITE DOCUMENTATION -->
+ */
 export default class Cursors extends EventEmitter<CursorsEventMap> {
   private readonly cursorBatching: CursorBatching;
   private readonly cursorDispensing: CursorDispensing;
@@ -45,6 +76,66 @@ export default class Cursors extends EventEmitter<CursorsEventMap> {
    *
    * @param {CursorUpdate} cursor
    * @return {void}
+   *
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from the [Spaces documentation website](https://ably.com/docs/spaces).
+   * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/content/spaces/cursors.textile?plain=1#L21-L74) -->
+   * Set the position of a member's cursor using the @set()@ method. A position must contain an X-axis value and a Y-axis value to set the cursor position on a 2D plane. Calling @set()@ will emit a cursor event so that other members are informed of the cursor movement in realtime.
+   *
+   * A member must have been "entered":/spaces/space#enter into the space to set their cursor position.
+   *
+   * The @set()@ method takes the following parameters:
+   *
+   * |_. Parameter |_. Description |_. Type |
+   * | 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, such as a color. | Object |
+   *
+   * <aside data-type='note'>
+   * <p>The @data@ parameter can be used to stream additional information related to a cursor's movement, such as:</p>
+   * <ul><li>The color that other member's should display a cursor as.</li>
+   * <li>The ID of an element that a user may be dragging for drag and drop functionality.</li>
+   * <li>Details of any cursor annotations.</li></ul>
+   * <p>Be aware that as live cursor updates are batched it is not advisable to publish data unrelated to cursor position in the @data@ parameter. Use a "pub/sub channel":/channels instead.</p>
+   * </aside>
+   *
+   * The following is an example of a member setting their cursor position by adding an event listener to obtain their cursor coordinates and then publishing their position using the @set()@ method:
+   *
+   * ```[javascript]
+   * window.addEventListener('mousemove', ({ clientX, clientY }) => {
+   *   space.cursors.set({ position: { x: clientX, y: clientY }, data: { color: 'red' } });
+   * });
+   * ```
+   *
+   * The following is an example payload of a cursor event. Cursor events are uniquely identifiable by the @connectionId@ of a cursor.
+   *
+   * ```[json]
+   * {
+   *   "hd9743gjDc": {
+   *     "connectionId": "hd9743gjDc",
+   *     "clientId": "clemons#142",
+   *     "position": {
+   *       "x": 864,
+   *       "y": 32
+   *     },
+   *     "data": {
+   *       "color": "red"
+   *     }
+   *   }
+   * }
+   * ```
+   *
+   * The following are the properties of a cursor event payload:
+   *
+   * |_. Property |_. Description |_. Type |
+   * | connectionId | The unique identifier of the member's "connection":/connect. | String |
+   * | clientId | The "client identifier":/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 |
+   * <!-- END WEBSITE DOCUMENTATION -->
    */
   async set(cursor: Pick<CursorUpdate, 'position' | 'data'>) {
     const self = await this.space.members.getSelf();
@@ -100,6 +191,26 @@ export default class Cursors extends EventEmitter<CursorsEventMap> {
     );
   };
 
+  /**
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from the [Spaces documentation website](https://ably.com/docs/spaces).
+   * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/content/spaces/cursors.textile?plain=1#L78-L90) -->
+   * Subscribe to cursor events by registering a listener. Cursor events are emitted whenever a member moves their cursor by calling @set()@. Use the @subscribe()@ method on the @cursors@ object of a space to receive updates.
+   *
+   * <aside data-type='note'>
+   * <p>The rate at which cursor events are published is controlled by the @outboundBatchInterval@ property set in the "cursor options":#options of a space.</p>
+   * </aside>
+   *
+   * The following is an example of subscribing to cursor events:
+   *
+   * ```[javascript]
+   * space.cursors.subscribe('update', (cursorUpdate) => {
+   *   console.log(cursorUpdate);
+   * });
+   * ```
+   * <!-- END WEBSITE DOCUMENTATION -->
+   */
   subscribe<K extends keyof CursorsEventMap>(
     eventOrEvents: K | K[],
     listener?: EventListener<CursorsEventMap, K>,
@@ -130,6 +241,26 @@ export default class Cursors extends EventEmitter<CursorsEventMap> {
     }
   }
 
+  /**
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from the [Spaces documentation website](https://ably.com/docs/spaces).
+   * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/content/spaces/cursors.textile?plain=1#L94-L106) -->
+   * Unsubscribe from cursor events to remove previously registered listeners.
+   *
+   * The following is an example of removing a listener for cursor update events:
+   *
+   * ```[javascript]
+   * space.cursors.unsubscribe(`update`, listener);
+   * ```
+   *
+   * Or remove all listeners:
+   *
+   * ```[javascript]
+   * space.cursors.unsubscribe();
+   * ```
+   * <!-- END WEBSITE DOCUMENTATION -->
+   */
   unsubscribe<K extends keyof CursorsEventMap>(
     eventOrEvents: K | K[],
     listener?: EventListener<CursorsEventMap, K>,
@@ -159,6 +290,10 @@ export default class Cursors extends EventEmitter<CursorsEventMap> {
     }
   }
 
+  /**
+   * <!-- This is to avoid duplication of the website documentation. -->
+   * See the documentation for {@link getAll}.
+   */
   async getSelf(): Promise<CursorUpdate | null> {
     const self = await this.space.members.getSelf();
     if (!self) return null;
@@ -167,6 +302,10 @@ export default class Cursors extends EventEmitter<CursorsEventMap> {
     return allCursors[self.connectionId];
   }
 
+  /**
+   * <!-- This is to avoid duplication of the website documentation. -->
+   * See the documentation for {@link getAll}.
+   */
   async getOthers(): Promise<Record<string, null | CursorUpdate>> {
     const self = await this.space.members.getSelf();
     if (!self) return {};
@@ -177,6 +316,99 @@ export default class Cursors extends EventEmitter<CursorsEventMap> {
     return allCursorsFiltered;
   }
 
+  /**
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from the [Spaces documentation website](https://ably.com/docs/spaces).
+   * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/content/spaces/cursors.textile?plain=1#L126-L211) -->
+   * Cursor positions can be retrieved in one-off calls. These are local calls that retrieve the latest position of cursors retained in memory by the SDK.
+   *
+   * The following is an example of retrieving a member's own cursor position:
+   *
+   * ```[javascript]
+   * const myCursor = await space.cursors.getSelf();
+   * ```
+   *
+   * The following is an example payload returned by @space.cursors.getSelf()@:
+   *
+   * ```[json]
+   * {
+   *   “clientId”: “DzOBJqgGXzyUBb816Oa6i”,
+   *   “connectionId”: “__UJBKZchX”,
+   *   "position": {
+   *     "x": 864,
+   *     "y": 32
+   *   }
+   * }
+   * ```
+   *
+   * The following is an example of retrieving the cursor positions for all members other than the member themselves:
+   *
+   * ```[javascript]
+   * const othersCursors = await space.cursors.getOthers();
+   * ```
+   *
+   * The following is an example payload returned by @space.cursors.getOthers()@:
+   *
+   * ```[json]
+   * {
+   *   "3ej3q7yZZz": {
+   *       "clientId": "yyXidHatpP3hJpMpXZi8W",
+   *       "connectionId": "3ej3q7yZZz",
+   *       "position": {
+   *         "x": 12,
+   *         "y": 3
+   *       }
+   *   },
+   *   "Z7CA3-1vlR": {
+   *       "clientId": "b18mj5B5hm-govdFEYRyb",
+   *       "connectionId": "Z7CA3-1vlR",
+   *       "position": {
+   *         "x": 502,
+   *         "y": 43
+   *       }
+   *   }
+   * }
+   * ```
+   *
+   * The following is an example of retrieving the cursor positions for all members, including the member themselves. @getAll()@ is useful for retrieving the initial position of members' cursors.
+   *
+   * ```[javascript]
+   * const allCursors = await space.cursors.getAll();
+   * ```
+   *
+   * The following is an example payload returned by @space.cursors.getAll()@:
+   *
+   * ```[json]
+   * {
+   *   "3ej3q7yZZz": {
+   *       "clientId": "yyXidHatpP3hJpMpXZi8W",
+   *       "connectionId": "3ej3q7yZZz",
+   *       "position": {
+   *         "x": 12,
+   *         "y": 3
+   *       }
+   *   },
+   *   "Z7CA3-1vlR": {
+   *       "clientId": "b18mj5B5hm-govdFEYRyb",
+   *       "connectionId": "Z7CA3-1vlR",
+   *       "position": {
+   *         "x": 502,
+   *         "y": 43
+   *       }
+   *   },
+   *   "__UJBKZchX": {
+   *       “clientId”: “DzOBJqgGXzyUBb816Oa6i”,
+   *       “connectionId”: “__UJBKZchX”,
+   *       "position": {
+   *         "x": 864,
+   *         "y": 32
+   *       }
+   *   }
+   * }
+   * ```
+   * <!-- END WEBSITE DOCUMENTATION -->
+   */
   async getAll(): Promise<Record<string, null | CursorUpdate>> {
     const channel = this.getChannel();
     return await this.cursorHistory.getLastCursorUpdate(channel, this.options.paginationLimit);
diff --git a/src/Locations.ts b/src/Locations.ts
index ddf78885..7764f991 100644
--- a/src/Locations.ts
+++ b/src/Locations.ts
@@ -18,6 +18,27 @@ export interface LocationsEventMap {
   update: LocationsEvents.UpdateEvent;
 }
 
+/**
+ * > **Documentation source**
+ * >
+ * > The following documentation is copied from the [Spaces documentation website](https://ably.com/docs/spaces).
+ * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/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.
+ * <!-- END WEBSITE DOCUMENTATION -->
+ *
+ * > **Documentation source**
+ * >
+ * > The following documentation is copied from the [Spaces documentation website](https://ably.com/docs/spaces).
+ * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/content/spaces/locations.textile?plain=1#L211-L215) -->
+ * h2(#foundations). 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":/presence-occupancy/presence feature. Members are entered into the presence set when they "enter the space":/spaces/space#enter.
+ * <!-- END WEBSITE DOCUMENTATION -->
+ */
 export default class Locations extends EventEmitter<LocationsEventMap> {
   private lastLocationUpdate: Record<string, PresenceMember['data']['locationUpdate']['id']> = {};
 
@@ -55,6 +76,24 @@ export default class Locations extends EventEmitter<LocationsEventMap> {
     }
   }
 
+  /**
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from the [Spaces documentation website](https://ably.com/docs/spaces).
+   * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/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.
+   *
+   * A member must have been "entered":/spaces/space#enter into the space to set their location.
+   *
+   * 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@.
+   *
+   * 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 -->
+   */
   async set(location: unknown) {
     const self = await this.space.members.getSelf();
 
@@ -66,6 +105,76 @@ export default class Locations extends EventEmitter<LocationsEventMap> {
     await this.presenceUpdate(update.updateLocation(location));
   }
 
+  /**
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from the [Spaces documentation website](https://ably.com/docs/spaces).
+   * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/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.
+   *
+   * 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@.
+   *
+   * <aside data-type='note'>
+   * <p> 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.</p>
+   * </aside>
+   *
+   * The following is an example of subscribing to location events:
+   *
+   * ```[javascript]
+   * space.locations.subscribe('update', (locationUpdate) => {
+   *   console.log(locationUpdate);
+   * });
+   * ```
+   *
+   * The following is an example payload of a location event. Information about location is returned in @currentLocation@ and @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:
+   *
+   * |_. Property |_. Description |_.  Type |
+   * | member.clientId | The "client identifier":/auth/identified-clients for the member. | String |
+   * | member.connectionId | The unique identifier of the member's "connection":/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.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 |
+   *
+   * <aside data-type='further-reading'>
+   * <p>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, "space state":/spaces/space can be subscribed to which returns an array of all members with their latest state every time any event is triggered.</p>
+   * </aside>
+   * <!-- END WEBSITE DOCUMENTATION -->
+   */
   subscribe<K extends keyof LocationsEventMap>(
     eventOrEvents: K | K[],
     listener?: EventListener<LocationsEventMap, K>,
@@ -88,6 +197,26 @@ export default class Locations extends EventEmitter<LocationsEventMap> {
     }
   }
 
+  /**
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from the [Spaces documentation website](https://ably.com/docs/spaces).
+   * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/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 -->
+   */
   unsubscribe<K extends keyof LocationsEventMap>(
     eventOrEvents: K | K[],
     listener?: EventListener<LocationsEventMap, K>,
@@ -110,11 +239,19 @@ export default class Locations extends EventEmitter<LocationsEventMap> {
     }
   }
 
+  /**
+   * <!-- This is to avoid duplication of the website documentation. -->
+   * See the documentation for {@link getAll}.
+   */
   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}.
+   */
   async getOthers(): Promise<Record<string, unknown>> {
     const members = await this.space.members.getOthers();
 
@@ -124,6 +261,75 @@ export default class Locations extends EventEmitter<LocationsEventMap> {
     }, {});
   }
 
+  /**
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from the [Spaces documentation website](https://ably.com/docs/spaces).
+   * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/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@:
+   *
+   * ```[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:
+   *
+   * ```[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 -->
+   */
   async getAll(): Promise<Record<string, unknown>> {
     const members = await this.space.members.getAll();
     return members.reduce((acc: Record<string, unknown>, member: SpaceMember) => {
diff --git a/src/Locks.ts b/src/Locks.ts
index 309daffb..0672c612 100644
--- a/src/Locks.ts
+++ b/src/Locks.ts
@@ -22,6 +22,42 @@ export interface LocksEventMap {
   update: Lock;
 }
 
+/**
+ * > **Documentation source**
+ * >
+ * > The following documentation is copied from the [Spaces documentation website](https://ably.com/docs/spaces).
+ * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/content/spaces/locking.textile?plain=1#L9-L37) -->
+ * The component locking feature enables members to optimistically lock stateful UI components before editing them. This reduces the chances of conflicting changes being made to the same component by different members. A component could be a cell in a spreadsheet that a member is updating, or an input field on a form they're filling in.
+ *
+ * Once a lock has been acquired by a member, the component that it relates to can be updated in the UI to visually indicate to other members that it is locked and and which member has the lock. The component can then be updated once the editing member has released the lock to indicate that it is now unlocked.
+ *
+ * Each lock is identified by a unique string ID, and only a single member may hold a lock with a given string at any one time. A lock will exist in one of three "states":#states and may only transition between states in specific circumstances.
+ *
+ * <aside data-type='important'>
+ * <p>Optimistic locking means that there is a chance that two members may begin editing the same UI component before it is confirmed which member holds the lock. On average, the time taken to reconcile which member holds a lock is in the hundreds of milliseconds. Your application needs to handle the member that successfully obtained the lock, as well as the member that had their request invalidated.</p>
+ * </aside>
+ *
+ * h2(#states). Lock states
+ *
+ * Component locking is handled entirely client-side. Members may begin to optimistically edit a component as soon as they call "@acquire()@":#acquire on the lock identifier related to it. Alternatively, you could wait until they receive a @locked@ event and display a spinning symbol in the UI until this is received. In either case a subsequent @unlocked@ event may invalidate that member's lock request if another member acquired it earlier. The time for confirmation of whether a lock request was successful or rejected is, on average, in the hundreds of milliseconds, however your code should handle all possible lock state transitions.
+ *
+ * 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.
+ *
+ * The following lock state transitions may occur:
+ *
+ * * None → @pending@: a member calls "@acquire()@":#acquire to request a lock.
+ * * @pending@ → @locked@: the requesting member holds the lock.
+ * * @pending@ → @unlocked@: the requesting member does not hold the lock, since another member already holds it.
+ * * @locked@ → @unlocked@: the lock was either explicitly "released":#release by the member, or their request was invalidated by a concurrent request which took precedence.
+ * * @unlocked@ → @locked@: the requesting member reacquired a lock they previously held.
+ *
+ * Only transitions that result in a @locked@ or @unlocked@ status will emit a lock event that members can "@subscribe()@":#subscribe to.
+ * <!-- END WEBSITE DOCUMENTATION -->
+ */
 export default class Locks extends EventEmitter<LocksEventMap> {
   // locks tracks the local state of locks, which is used to determine whether
   // a lock's status has changed when processing presence updates.
@@ -37,6 +73,35 @@ export default class Locks extends EventEmitter<LocksEventMap> {
     this.locks = new Map();
   }
 
+  /**
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from the [Spaces documentation website](https://ably.com/docs/spaces).
+   * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/content/spaces/locking.textile?plain=1#L171-L192) -->
+   * Use the @get()@ method to query whether a lock is currently locked, and by which member if it is. The lock is identifiable by its unique string ID.
+   *
+   * The following is an example of checking whether a lock identifier is currently locked:
+   *
+   * ```[javascript]
+   * const isLocked = space.locks.get(id) !== undefined;
+   * ```
+   *
+   * The following is an example of checking which member holds the lock:
+   *
+   * ```[javascript]
+   * const { member } = space.locks.get(id);
+   * ```
+   *
+   * The following is an example of viewing the attributes assigned to the lock by the member holding it:
+   *
+   * ```[javascript]
+   * const { request } = space.locks.get(id);
+   * const viewLock = request.attributes.get(key);
+   * ```
+   *
+   * If the lock is not currently held by a member, @get()@ will return @undefined@. Otherwise it will return the most recent lock event for the lock.
+   * <!-- END WEBSITE DOCUMENTATION -->
+   */
   get(id: string): Lock | undefined {
     const locks = this.locks.get(id);
     if (!locks) return;
@@ -49,6 +114,65 @@ export default class Locks extends EventEmitter<LocksEventMap> {
 
   // This will be async in the future, when pending requests are no longer processed
   // in the library.
+  /**
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from the [Spaces documentation website](https://ably.com/docs/spaces).
+   * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/content/spaces/locking.textile?plain=1#L196-L247) -->
+   * Locks can also be retrieved in one-off calls. These are local calls and retrieve the locks retained in memory by the SDK.
+   *
+   * The following is an example of retrieving an array of all currently held locks in a space:
+   *
+   * ```[javascript]
+   * const allLocks = await space.locks.getAll();
+   * ```
+   *
+   * The following is an example payload returned by @space.locks.getAll()@:
+   *
+   * ```[json]
+   * [
+   *   {
+   *     "id": "s1-c2",
+   *     "status": "locked",
+   *     "timestamp": 1247525627533,
+   *     "member": {
+   *       "clientId": "amint#5",
+   *       "connectionId": "hg35a4fgjAs",
+   *       "isConnected": true,
+   *         "lastEvent": {
+   *         "name": "update",
+   *       "timestamp": 173459567340
+   *       },
+   *       "location": null,
+   *       "profileData": {
+   *         "username": "Arit Mint",
+   *         "avatar": "https://slides-internal.com/users/amint.png"
+   *       }
+   *     }
+   *   },
+   *   {
+   *     "id": "s3-c4",
+   *     "status": "locked",
+   *     "timestamp": 1247115627423,
+   *     "member": {
+   *       "clientId": "torange#1",
+   *       "connectionId": "tt7233ghUa",
+   *       "isConnected": true,
+   *       "lastEvent": {
+   *         "name": "update",
+   *         "timestamp": 167759566354
+   *       },
+   *       "location": null,
+   *       "profileData": {
+   *         "username": "Tara Orange",
+   *         "avatar": "https://slides-internal.com/users/torange.png"
+   *       }
+   *     }
+   *   }
+   * ]
+   * ```
+   * <!-- END WEBSITE DOCUMENTATION -->
+   */
   async getAll(): Promise<Lock[]> {
     const allLocks: Lock[] = [];
 
@@ -63,6 +187,10 @@ export default class Locks extends EventEmitter<LocksEventMap> {
     return allLocks;
   }
 
+  /**
+   * <!-- This is to avoid duplication of the website documentation. -->
+   * See the documentation for {@link getAll}.
+   */
   async getSelf(): Promise<Lock[]> {
     const self = await this.space.members.getSelf();
 
@@ -71,6 +199,10 @@ export default class Locks extends EventEmitter<LocksEventMap> {
     return this.getLocksForConnectionId(self.connectionId).filter((lock) => lock.status === 'locked');
   }
 
+  /**
+   * <!-- This is to avoid duplication of the website documentation. -->
+   * See the documentation for {@link getAll}.
+   */
   async getOthers(): Promise<Lock[]> {
     const self = await this.space.members.getSelf();
     const allLocks = await this.getAll();
@@ -80,6 +212,45 @@ export default class Locks extends EventEmitter<LocksEventMap> {
     return allLocks.filter((lock) => lock.member.connectionId !== self.connectionId);
   }
 
+  /**
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from the [Spaces documentation website](https://ably.com/docs/spaces).
+   * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/content/spaces/locking.textile?plain=1#L41-L72) -->
+   * Use the @acquire()@ method to attempt to acquire a lock with a given unique ID. Additional @attributes@ may be passed when trying to acquire a lock that can contain a set of arbitrary key-value pairs. An example of using @attributes@ is to store the component ID the lock relates to so that it can be easily updated in the UI with a visual indication of its lock status.
+   *
+   * A member must have been "entered":/spaces/space#enter into the space to acquire a lock.
+   *
+   * The following is an example of attempting to acquire a lock:
+   *
+   * ```[javascript]
+   * const acquireLock = await space.locks.acquire(id);
+   * ```
+   *
+   * The following is an example of passing a set of @attributes@ when trying to acquire a lock:
+   *
+   * ```[javascript]
+   * const lockAttributes = new Map();
+   * lockAttributes.set('component', 'cell-d3');
+   * const acquireLock = await space.locks.acquire(id, { lockAttributes });
+   * ```
+   *
+   * The following is an example payload returned by @space.locks.acquire()@. The promise will resolve to a lock request with the @pending@ status:
+   *
+   * ```[json]
+   * {
+   *   "id": "s2-d14",
+   *   "status": "pending",
+   *   "timestamp": 1247525689781,
+   *   "attributes": {
+   *     "componentId": "cell-d14"
+   *   }
+   * }
+   * ```
+   *
+   * Once a member requests a lock by calling @acquire()@, the lock is temporarily in the "pending state":#states. An event will be emitted based on whether the lock request was successful (a status of @locked@) or invalidated (a status of @unlocked@). This can be "subscribed":#subscribe to in order for the client to know whether their lock request was successful or not.
+   * <!-- END WEBSITE DOCUMENTATION -->
+   */
   async acquire(id: string, opts?: LockOptions): Promise<Lock> {
     const self = await this.space.members.getSelf();
     if (!self) {
@@ -113,6 +284,26 @@ export default class Locks extends EventEmitter<LocksEventMap> {
     return lock;
   }
 
+  /**
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from the [Spaces documentation website](https://ably.com/docs/spaces).
+   * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/content/spaces/locking.textile?plain=1#L76-L88) -->
+   * Use the @release()@ method to explicitly release a lock once a member has finished editing the related component. For example, the @release()@ method can be called once a user clicks outside of the component, such as clicking on another cell within a spreadsheet. Any UI indications that the previous cell was locked can then be cleared.
+   *
+   * The following is an example of releasing a lock:
+   *
+   * ```[javascript]
+   * await space.locks.release(id);
+   * ```
+   *
+   * Releasing a lock will emit a lock event with a "lock status":#states of @unlocked@.
+   *
+   * <aside data-type='note'>
+   * <p>When a member "leaves":/spaces/space#leave a space, their locks are automatically released.</p>
+   * </aside>
+   * <!-- END WEBSITE DOCUMENTATION -->
+   */
   async release(id: string): Promise<void> {
     const self = await this.space.members.getSelf();
 
@@ -131,6 +322,73 @@ export default class Locks extends EventEmitter<LocksEventMap> {
     this.deleteLock(id, self.connectionId);
   }
 
+  /**
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from the [Spaces documentation website](https://ably.com/docs/spaces).
+   * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/content/spaces/locking.textile?plain=1#L92-L151) -->
+   * Subscribe to lock events by registering a listener. Lock events are emitted whenever the "lock state":#states transitions into @locked@ or @unlocked@. Use the @subscribe()@ method on the @locks@ namespace of the space to receive updates.
+   *
+   * All lock events are @update@ events. When a lock event is received, UI components can be updated to add and remove visual indications of which member is locking them, as well as enabling and disabling the ability for other members to edit them.
+   *
+   * The following is an example of subscribing to lock events:
+   *
+   * ```[javascript]
+   * space.locks.subscribe('update', (lock) => {
+   *   console.log(lock);
+   * });
+   * ```
+   *
+   * The following is an example payload of a lock event:
+   *
+   * ```json
+   * {
+   *   "id": "s2-d14",
+   *   "status": "unlocked",
+   *   "timestamp": 1247525689781,
+   *   "attributes": {
+   *     "componentId": "cell-d14"
+   *   },
+   *   "reason": {
+   *     "message": "lock is currently locked",
+   *     "code": 101003,
+   *     "statusCode": 400
+   *   },
+   *   "member": {
+   *     "clientId": "smango",
+   *     "connectionId": "hs343gjsdc",
+   *     "isConnected": true,
+   *     "profileData": {
+   *       "username": "Saiorse Mango"
+   *     },
+   *     "location": {
+   *       "slide": "sheet-2",
+   *       "component": "d-14"
+   *     },
+   *     "lastEvent": {
+   *       "name": "update",
+   *       "timestamp": 1247525689781
+   *     }
+   *   }
+   * }
+   * ```
+   *
+   * 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":/auth/identified-clients for the member. | String |
+   * | member.connectionId | The unique identifier of the member's "connection":/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 |
+   * <!-- END WEBSITE DOCUMENTATION -->
+   */
   subscribe<K extends keyof LocksEventMap>(eventOrEvents: K | K[], listener?: EventListener<LocksEventMap, K>): void;
   subscribe(listener?: EventListener<LocksEventMap, keyof LocksEventMap>): void;
   subscribe<K extends keyof LocksEventMap>(
@@ -150,6 +408,26 @@ export default class Locks extends EventEmitter<LocksEventMap> {
     }
   }
 
+  /**
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from the [Spaces documentation website](https://ably.com/docs/spaces).
+   * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/content/spaces/locking.textile?plain=1#L155-L166) -->
+   * Unsubscribe from lock events to remove previously registered listeners.
+   *
+   * The following is an example of removing a listener for lock update events:
+   *
+   * ```[javascript]
+   * space.locks.unsubscribe('update', listener);
+   * ```
+   *
+   * Or remove all listeners:
+   *
+   * ```[javascript]
+   * space.locks.unsubscribe();
+   * ```
+   * <!-- END WEBSITE DOCUMENTATION -->
+   */
   unsubscribe<K extends keyof LocksEventMap>(eventOrEvents: K | K[], listener?: EventListener<LocksEventMap, K>): void;
   unsubscribe(listener?: EventListener<LocksEventMap, keyof LocksEventMap>): void;
   unsubscribe<K extends keyof LocksEventMap>(
diff --git a/src/Members.ts b/src/Members.ts
index b058fc4b..8b714d84 100644
--- a/src/Members.ts
+++ b/src/Members.ts
@@ -13,6 +13,40 @@ export interface MembersEventMap {
   remove: SpaceMember;
 }
 
+/**
+ * > **Documentation source**
+ * >
+ * > The following documentation is copied from the Spaces documentation website.
+ * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/14acea6dee7bf3872a3d32d43732f934cbe93a7d/content/spaces/avatar.textile?plain=1#L9-L24) -->
+ * Avatar stacks are the most common way of showing the online status of members in an application by displaying an avatar for each member. Events are emitted whenever a member enters or leaves a space, or updates their profile data. Additional information can also be provided, such as a profile picture and email address.
+ *
+ * Subscribe to the @space.members@ namespace in order to keep your avatar stack updated in realtime.
+ *
+ * h2(#events). Event types
+ *
+ * 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.
+ *
+ * <aside data-type='note'>
+ * <p>Members "enter":/spaces/space#enter, "leave":/spaces/space#leave, and "update":/spaces/space#update-profile a "space":/spaces/space directly. The @members@ namespace is used to subscribe to these updates.</p>
+ * </aside>
+ * <!-- END WEBSITE DOCUMENTATION -->
+ *
+ * > **Documentation source**
+ * >
+ * > The following documentation is copied from the Spaces documentation website.
+ * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/14acea6dee7bf3872a3d32d43732f934cbe93a7d/content/spaces/avatar.textile?plain=1#L296-L300) -->
+ * h2(#foundations). Avatar stack 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.
+ *
+ * Avatar stacks build upon the functionality of the Pub/Sub Channels "presence":/presence-occupancy/presence feature. Members are entered into the presence set when they "enter the space":/spaces/space#enter.
+ * <!-- END WEBSITE DOCUMENTATION -->
+ */
 class Members extends EventEmitter<MembersEventMap> {
   private lastMemberUpdate: Record<string, PresenceMember['data']['profileUpdate']['id']> = {};
   private leavers: Leavers;
@@ -51,21 +85,240 @@ class Members extends EventEmitter<MembersEventMap> {
     }
   }
 
+  /**
+   * <!-- This is to avoid duplication of the website documentation. -->
+   * See the documentation for {@link getAll}.
+   */
   async getSelf(): Promise<SpaceMember | null> {
     return this.space.connectionId ? await this.getByConnectionId(this.space.connectionId) : null;
   }
 
+  /**
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from the Spaces documentation website.
+   * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/14acea6dee7bf3872a3d32d43732f934cbe93a7d/content/spaces/avatar.textile?plain=1#L128-L249) -->
+   * Space membership can be retrieved in one-off calls. These are local calls and retrieve the membership retained in memory by the SDK. One-off calls to retrieve membership can be used for operations such as displaying a member's own profile data to them, or retrieving a list of all other members to use to "update their profile data":/spaces/space#update-profile.
+   *
+   * The following is an example of retrieving a member's own member object:
+   *
+   * ```[javascript]
+   * const myMemberInfo = await space.members.getSelf();
+   * ```
+   *
+   * The following is an example payload returned by @space.members.getSelf()@:
+   *
+   * ```[json]
+   *   {
+   *     "clientId": "clemons#142",
+   *     "connectionId": "hd9743gjDc",
+   *     "isConnected": true,
+   *     "lastEvent": {
+   *       "name": "enter",
+   *       "timestamp": 1677595689759
+   *     },
+   *     "location": null,
+   *     "profileData": {
+   *       "username": "Claire Lemons",
+   *       "avatar": "https://slides-internal.com/users/clemons.png"
+   *     }
+   *   }
+   * ```
+   *
+   * The following is an example of retrieving an array of member objects for all members other than the member themselves. Ths includes members that have recently left the space, but have not yet been removed.
+   *
+   * ```[javascript]
+   * const othersMemberInfo = await space.members.getOthers();
+   * ```
+   *
+   * The following is an example payload returned by @space.members.getOthers()@:
+   *
+   * ```[json]
+   * [
+   *   {
+   *     "clientId": "torange#1",
+   *     "connectionId": "tt7233ghUa",
+   *     "isConnected": true,
+   *     "lastEvent": {
+   *       "name": "enter",
+   *       "timestamp": 167759566354
+   *     },
+   *     "location": null,
+   *     "profileData": {
+   *       "username": "Tara Orange",
+   *       "avatar": "https://slides-internal.com/users/torange.png"
+   *     }
+   *   },
+   *   {
+   *       "clientId": "amint#5",
+   *       "connectionId": "hg35a4fgjAs",
+   *       "isConnected": true,
+   *         "lastEvent": {
+   *         "name": "update",
+   *       "timestamp": 173459567340
+   *       },
+   *       "location": null,
+   *       "profileData": {
+   *         "username": "Arit Mint",
+   *         "avatar": "https://slides-internal.com/users/amint.png"
+   *       }
+   *   }
+   * ]
+   * ```
+   *
+   * The following is an example of retrieving an array of all member objects, including the member themselves. Ths includes members that have recently left the space, but have not yet been removed.
+   *
+   * ```[javascript]
+   * const allMembers = await space.members.getAll();
+   * ```
+   *
+   * The following is an example payload returned by @space.members.getAll()@:
+   *
+   * ```[json]
+   * [
+   *   {
+   *     "clientId": "clemons#142",
+   *     "connectionId": "hd9743gjDc",
+   *     "isConnected": false,
+   *     "lastEvent": {
+   *       "name": "enter",
+   *       "timestamp": 1677595689759
+   *     },
+   *     "location": null,
+   *     "profileData": {
+   *       "username": "Claire Lemons",
+   *       "avatar": "https://slides-internal.com/users/clemons.png"
+   *     }
+   *   },
+   *   {
+   *       "clientId": "amint#5",
+   *       "connectionId": "hg35a4fgjAs",
+   *       "isConnected": true,
+   *         "lastEvent": {
+   *         "name": "update",
+   *       "timestamp": 173459567340
+   *       },
+   *       "location": null,
+   *       "profileData": {
+   *         "username": "Arit Mint",
+   *         "avatar": "https://slides-internal.com/users/amint.png"
+   *       }
+   *   },
+   *   {
+   *     "clientId": "torange#1",
+   *     "connectionId": "tt7233ghUa",
+   *     "isConnected": true,
+   *     "lastEvent": {
+   *       "name": "enter",
+   *       "timestamp": 167759566354
+   *     },
+   *     "location": null,
+   *     "profileData": {
+   *       "username": "Tara Orange",
+   *       "avatar": "https://slides-internal.com/users/torange.png"
+   *     }
+   *   }
+   * ]
+   * ```
+   * <!-- END WEBSITE DOCUMENTATION -->
+   */
   async getAll(): Promise<SpaceMember[]> {
     const presenceMembers = await this.space.channel.presence.get();
     const members = presenceMembers.map((m) => this.createMember(m));
     return members.concat(this.leavers.getAll().map((l) => l.member));
   }
 
+  /**
+   * <!-- This is to avoid duplication of the website documentation. -->
+   * See the documentation for {@link getAll}.
+   */
   async getOthers(): Promise<SpaceMember[]> {
     const members = await this.getAll();
     return members.filter((m) => m.connectionId !== this.space.connectionId);
   }
 
+  /**
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from the Spaces documentation website.
+   * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/14acea6dee7bf3872a3d32d43732f934cbe93a7d/content/spaces/avatar.textile?plain=1#L28-L102) -->
+   * Subscribe to members' online status and profile updates by registering a listener. Member events are emitted whenever a member "enters":/spaces/space#enter or "leaves":/spaces/space#leave the space, or updates their profile data. Use the @subscribe()@ method on the @members@ object of a space to receive updates.
+   *
+   * The following is an example of subscribing to the different member event types:
+   *
+   * ```[javascript]
+   * // Subscribe to member enters in a space
+   * space.members.subscribe('enter', (memberUpdate) => {
+   *   console.log(memberUpdate);
+   * });
+   *
+   * // Subscribe to member profile data updates in a space
+   * space.members.subscribe('update', (memberUpdate) => {
+   *   console.log(memberUpdate);
+   * });
+   *
+   * // Subscribe to member leaves in a space
+   * space.members.subscribe('leave', (memberUpdate) => {
+   *   console.log(memberUpdate);
+   * });
+   *
+   * // Subscribe to member removals in a space
+   * space.members.subscribe('remove', (memberUpdate) => {
+   *   console.log(memberUpdate);
+   * });
+   * ```
+   *
+   * It's also possible to subscribe to multiple event types with the same listener by using an array:
+   *
+   * ```[javascript]
+   * space.members.subscribe(['enter', 'update'], (memberUpdate) => {
+   *   console.log(memberUpdate);
+   * });
+   * ```
+   *
+   * Or subscribe to all event types:
+   *
+   * ```[javascript]
+   * space.members.subscribe((memberUpdate) => {
+   *   console.log(memberUpdate);
+   * });
+   * ```
+   *
+   * The following is an example payload of a member event. The @lastEvent.name@ describes which "event type":#events a payload relates to.
+   *
+   * ```[json]
+   *   {
+   *     "clientId": "clemons#142",
+   *     "connectionId": "hd9743gjDc",
+   *     "isConnected": true,
+   *     "lastEvent": {
+   *       "name": "enter",
+   *       "timestamp": 1677595689759
+   *     },
+   *     "location": null,
+   *     "profileData": {
+   *       "username": "Claire Lemons",
+   *       "avatar": "https://slides-internal.com/users/clemons.png"
+   *     }
+   *   }
+   * ```
+   *
+   * The following are the properties of a member event payload:
+   *
+   * |_. Property |_. Description |_. Type |
+   * | clientId | The "client identifier":/auth/identified-clients for the member. | String |
+   * | connectionId | The unique identifier of the member's "connection":/connect. | String |
+   * | isConnected | Whether the member is connected to Ably or not. | Boolean |
+   * | profileData | The optional "profile data":#profile-data associated with the member. | Object |
+   * | location | The current "location":/spaces/locations of the member. Will be @null@ for @enter@, @leave@ and @remove@ events. | Object |
+   * | lastEvent.name | The most recent event emitted by the member. | String |
+   * | lastEvent.timestamp | The timestamp of the most recently emitted event. | Number |
+   *
+   * <aside data-type='further-reading'>
+   * <p>Avatar stack subscription listeners only trigger on events related to members' online status and profile updates. Each event only contains the payload of the member that triggered it. Alternatively, "space state":/spaces/space can be subscribed to which returns an array of all members with their latest state every time any event is triggered.</p>
+   * </aside>
+   * <!-- END WEBSITE DOCUMENTATION -->
+   */
   subscribe<K extends keyof MembersEventMap>(
     eventOrEvents: K | K[],
     listener?: EventListener<MembersEventMap, K>,
@@ -88,6 +341,32 @@ class Members extends EventEmitter<MembersEventMap> {
     }
   }
 
+  /**
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from the Spaces documentation website.
+   * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/14acea6dee7bf3872a3d32d43732f934cbe93a7d/content/spaces/avatar.textile?plain=1#L106-L124) -->
+   * Unsubscribe from member events to remove previously registered listeners.
+   *
+   * The following is an example of removing a listener for one member event type:
+   *
+   * ```[javascript]
+   * space.members.unsubscribe('enter', listener);
+   * ```
+   *
+   * It's also possible to remove listeners for multiple member event types:
+   *
+   * ```[javascript]
+   * space.members.unsubscribe(['enter', 'leave'], listener);
+   * ```
+   *
+   * Or remove all listeners:
+   *
+   * ```[javascript]
+   * space.members.unsubscribe();
+   * ```
+   * <!-- END WEBSITE DOCUMENTATION -->
+   */
   unsubscribe<K extends keyof MembersEventMap>(
     eventOrEvents: K | K[],
     listener?: EventListener<MembersEventMap, K>,
diff --git a/src/Space.ts b/src/Space.ts
index dfba8a16..71f92a1b 100644
--- a/src/Space.ts
+++ b/src/Space.ts
@@ -34,6 +34,27 @@ export interface SpaceEventMap {
   update: SpaceEvents.UpdateEvent;
 }
 
+/**
+ * > **Documentation source**
+ * >
+ * > The following documentation is copied from the [Spaces documentation website](https://ably.com/docs/spaces).
+ * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/content/spaces/space.textile?plain=1#L9-L22) -->
+ * A space is a virtual area of your application in which realtime collaboration between users can take place. You can have any number of virtual spaces within an application, with a single space being anything from a web page, a sheet within a spreadsheet, an individual slide in a slideshow, or the entire slideshow itself.
+ *
+ * The following features can be implemented within a space:
+ *
+ * * "Avatar stack":/spaces/avatar
+ * * "Member location":/spaces/locations
+ * * "Live cursors":/spaces/cursors
+ * * "Component locking":/spaces/locking
+ *
+ * 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.
+ *
+ * To subscribe to any events in a space, you first need to create or retrieve a space.
+ * <!-- END WEBSITE DOCUMENTATION -->
+ */
 class Space extends EventEmitter<SpaceEventMap> {
   private readonly channelName: string;
   readonly connectionId: string | undefined;
@@ -107,6 +128,44 @@ class Space extends EventEmitter<SpaceEventMap> {
     this.emit('update', { members: await this.members.getAll() });
   }
 
+  /**
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from the [Spaces documentation website](https://ably.com/docs/spaces).
+   * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/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.
+   *
+   * Being entered into a space is required for members to:
+   *
+   * * Update their "profile data":#update-profile.
+   * * Set their "location":/spaces/locations.
+   * * Set their "cursor position":/spaces/cursors.
+   *
+   * The following is an example of entering a space:
+   *
+   * ```[javascript]
+   * await space.enter();
+   * ```
+   * <!-- END WEBSITE DOCUMENTATION -->
+   *
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from the [Spaces documentation website](https://ably.com/docs/spaces).
+   * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/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.
+   *
+   * Profile data is returned in the payload of all space events.
+   *
+   * The following is an example of setting profile data when entering a space:
+   *
+   * ```[javascript]
+   * await space.enter({
+   *   username: 'Claire Oranges',
+   *   avatar: 'https://slides-internal.com/users/coranges.png',
+   * });
+   * ```
+   * <!-- END WEBSITE DOCUMENTATION -->
+   */
   async enter(profileData: ProfileData = null): Promise<SpaceMember[]> {
     return new Promise((resolve) => {
       const presence = this.channel.presence;
@@ -129,6 +188,28 @@ class Space extends EventEmitter<SpaceEventMap> {
     });
   }
 
+  /**
+   * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/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.
+   *
+   * The following is an example of updating profile data:
+   *
+   * ```[javascript]
+   * space.updateProfileData({
+   *   username: 'Claire Lemons',
+   *   avatar: 'https://slides-internal.com/users/clemons.png',
+   * });
+   * ```
+   *
+   * A function can be passed to @updateProfileData()@ in order to update a field based on the existing profile data:
+   *
+   * ```[javascript]
+   * space.updateProfileData(currentProfile => {
+   *   return { ...currentProfile, username: 'Clara Lemons' }
+   * });
+   * ```
+   * <!-- END WEBSITE DOCUMENTATION -->
+   */
   async updateProfileData(profileDataOrUpdateFn: ProfileData | ((update: ProfileData) => ProfileData)): Promise<void> {
     const self = await this.members.getSelf();
 
@@ -154,6 +235,19 @@ class Space extends EventEmitter<SpaceEventMap> {
     }
   }
 
+  /*
+   * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/content/spaces/space.textile?plain=1#L59-L67) -->
+   * Leaving a space will emit a "@leave@":/spaces/members#events event to all subscribers.
+   *
+   * The following is an example of explicitly leaving a space:
+   *
+   * ```[javascript]
+   * await space.leave();
+   * ```
+   *
+   * Members will implicitly leave a space after 15 seconds if they abruptly disconnect. If experiencing network disruption, and they reconnect within 15 seconds, then they will remain part of the space and no @leave@ event will be emitted.
+   * <!-- END WEBSITE DOCUMENTATION -->
+   */
   async leave(profileData: ProfileData = null) {
     const self = await this.members.getSelf();
 
@@ -174,11 +268,97 @@ class Space extends EventEmitter<SpaceEventMap> {
     await this.presenceLeave(data);
   }
 
+  /**
+   * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/content/spaces/space.textile?plain=1#L191-L197) -->
+   * The current state of the space can be retrieved in a one-off call. This will return an array of all @member@ objects currently in the space. This is a local call and retrieves the membership of the space retained in memory by the SDK.
+   *
+   * The following is an example of retrieving the current space state. Ths includes members that have recently left the space, but have not yet been removed:
+   *
+   * ```[javascript]
+   * const spaceState = await space.getState();
+   * ```
+   * <!-- END WEBSITE DOCUMENTATION -->
+   */
   async getState(): Promise<{ members: SpaceMember[] }> {
     const members = await this.members.getAll();
     return { members };
   }
 
+  /**
+   * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/content/spaces/space.textile?plain=1#L107-L177) -->
+   * Subscribe to space state updates by registering a listener. Use the @subscribe()@ method on the @space@ object to receive updates.
+   *
+   * The following events will trigger a space event:
+   *
+   * * A member enters the space
+   * * A member leaves the space
+   * * A member is removed from the space state "after the offlineTimeout period":#options has elapsed
+   * * A member updates their profile data
+   * * A member sets a new location
+   *
+   * Space state contains a single object called @members@. Any events that trigger a change in space state will always return the current state of the space as an array of @member@ objects.
+   *
+   * <aside data-type='note'>
+   * <p>"Avatar stacks":/spaces/members and "member location":/spaces/locations events can be subscribed to on their individual namespaces; @space.members@ and @space.locations@. These events are filtered versions of space state events. Only a single "message":/channels/messages is published per event by Ably, irrespective of whether you register listeners for space state or individual namespaces. If you register listeners for both, it is still only a single message.</p>
+   * <p>The key difference between the subscribing to space state or to individual feature events, is that space state events return the current state of the space as an array of all members in each event payload. Individual member and location event payloads only include the relevant data for the member that triggered the event.</p>
+   * </aside>
+   *
+   * The following is an example of subscribing to space events:
+   *
+   * ```[javascript]
+   * space.subscribe('update', (spaceState) => {
+   *   console.log(spaceState.members);
+   * });
+   * ```
+   *
+   * The following is an example payload of a space event.
+   *
+   * ```[json]
+   * [
+   *     {
+   *         "clientId": "clemons#142",
+   *         "connectionId": "hd9743gjDc",
+   *         "isConnected": false,
+   *         "lastEvent": {
+   *           "name": "leave",
+   *           "timestamp": 1677595689759
+   *         },
+   *         "location": null,
+   *         "profileData": {
+   *           "username": "Claire Lemons",
+   *           "avatar": "https://slides-internal.com/users/clemons.png"
+   *         }
+   *     },
+   *     {
+   *         "clientId": "amint#5",
+   *         "connectionId": "hg35a4fgjAs",
+   *         "isConnected": true,
+   *           "lastEvent": {
+   *           "name": "enter",
+   *         "timestamp": 173459567340
+   *         },
+   *         "location": null,
+   *         "profileData": {
+   *           "username": "Arit Mint",
+   *           "avatar": "https://slides-internal.com/users/amint.png"
+   *         }
+   *     },
+   *     ...
+   * ]
+   * ```
+   *
+   * The following are the properties of an individual @member@ within a space event payload:
+   *
+   * |_. Property |_. Description |_. Type |
+   * | clientId | The "client identifier":/auth/identified-clients for the member. | String |
+   * | connectionId | The unique identifier of the member's "connection":/connect. | String |
+   * | isConnected | Whether the member is connected to Ably or not. | Boolean |
+   * | profileData | The optional "profile data":#profile-data associated with the member. | Object |
+   * | location | The current "location":/spaces/locations of the member. | Object |
+   * | lastEvent.name | The most recent event emitted by the member. | String |
+   * | lastEvent.timestamp | The timestamp of the most recently emitted event. | Number |
+   * <!-- END WEBSITE DOCUMENTATION -->
+   */
   subscribe<K extends keyof SpaceEventMap>(eventOrEvents: K | K[], listener?: EventListener<SpaceEventMap, K>): void;
   subscribe(listener?: EventListener<SpaceEventMap, keyof SpaceEventMap>): void;
   subscribe<K extends keyof SpaceEventMap>(
@@ -198,6 +378,17 @@ class Space extends EventEmitter<SpaceEventMap> {
     }
   }
 
+  /**
+   * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/content/spaces/space.textile?plain=1#L181-L187) -->
+   * Unsubscribe from space events to remove previously registered listeners.
+   *
+   * The following is an example of removing a listener:
+   *
+   * ```[javascript]
+   * space.unsubscribe('update', listener);
+   * ```
+   * <!-- END WEBSITE DOCUMENTATION -->
+   */
   unsubscribe<K extends keyof SpaceEventMap>(eventOrEvents: K | K[], listener?: EventListener<SpaceEventMap, K>): void;
   unsubscribe(listener?: EventListener<SpaceEventMap, keyof SpaceEventMap>): void;
   unsubscribe<K extends keyof SpaceEventMap>(
diff --git a/src/Spaces.ts b/src/Spaces.ts
index 5f252819..2e7eaddb 100644
--- a/src/Spaces.ts
+++ b/src/Spaces.ts
@@ -31,6 +31,98 @@ class Spaces {
     options.agents = { ...(options.agents ?? options.agents), ...agent };
   }
 
+  /**
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from the [Spaces documentation website](https://ably.com/docs/spaces).
+   * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/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.
+   *
+   * The following restrictions apply to space names:
+   *
+   * * Avoid starting names with @[@ or @:@
+   * * Ensure names aren't empty
+   * * Exclude whitespace and wildcards, such as @*@
+   * * Use the correct case, whether it be uppercase or lowercase
+   *
+   * The following is an example of creating a space:
+   *
+   * ```[javascript]
+   * const space = await spaces.get('board-presentation');
+   * ```
+   * <!-- END WEBSITE DOCUMENTATION -->
+   *
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from the [Spaces documentation website](https://ably.com/docs/spaces).
+   * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/content/spaces/space.textile?plain=1#L199-L242) -->
+   * h2(#advanced). Advanced properties
+   *
+   * The following sections are only relevant if you want to further customize a space, or understand more about the Spaces SDK. They aren't required to get up and running with the basics.
+   *
+   * h3(#options). Space options
+   *
+   * An additional set of optional properties may be passed when "creating or retrieving":#create a space to customize the behavior of different features.
+   *
+   * The following properties can be customized:
+   *
+   * |_. 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.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 |
+   *
+   * The following is an example of customizing the space options when calling @spaces.get()@:
+   *
+   * ```[javascript]
+   * const space = await spaces.get('board-presentation', {
+   * 	offlineTimeout: 180_000,
+   * 	cursors: { paginationLimit: 10 }
+   * });
+   * ```
+   *
+   * h3(#foundations). Space 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.
+   *
+   * A space is created as an Ably "channel":/channels. Members "attach":/channels#attach to the channel and join its "presence set":/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":/channels#states. The channel object can be accessed through @space.channel@.
+   *
+   * The following is an example of registering a listener to wait for a channel to become attached:
+   *
+   * ```[javascript]
+   * space.channel.on('attached', (stateChange) => {
+   *   console.log(stateChange)
+   * });
+   * ```
+   *
+   * <aside data-type='note'>
+   * <p>Due to the high frequency at which updates are streamed for cursor movements, live cursors utilizes its own "channel":/channels.</p>
+   * </aside>
+   * <!-- END WEBSITE DOCUMENTATION -->
+   *
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from the [Spaces documentation website](https://ably.com/docs/spaces).
+   * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/content/spaces/cursors.textile?plain=1#L108-L122) -->
+   * h2(#options). 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:
+   *
+   * h3(#batch). outboundBatchInterval
+   *
+   * The @outboundBatchInterval@ is the interval at which a batch of cursor positions are published, in milliseconds, for each client. This is multiplied by the number of members in a space.
+   *
+   * The default value is 25ms which is optimal for the majority of use cases. If you wish to optimize the interval further, then decreasing the value will improve performance by further 'smoothing' the movement of cursors at the cost of increasing the number of events sent. Be aware that at a certain point the rate at which a browser is able to render the changes will impact optimizations.
+   *
+   * h3(#pagination). paginationLimit
+   *
+   * The volume of messages sent can be high when using live cursors. Because of this, the last known position of every members' cursor is obtained from "history":/storage-history/history. The @paginationLimit@ is the number of pages that should be searched to find the last position of each cursor. The default is 5.
+   * <!-- END WEBSITE DOCUMENTATION -->
+   */
   async get(name: string, options?: Subset<SpaceOptions>): Promise<Space> {
     if (typeof name !== 'string' || name.length === 0) {
       throw ERR_SPACE_NAME_MISSING();

From e9d733ed6f1a8e10fbd75bf68b1c3dcc111d2208 Mon Sep 17 00:00:00 2001
From: Lawrence Forooghian <lawrence@forooghian.com>
Date: Tue, 26 Sep 2023 15:44:08 -0300
Subject: [PATCH 16/30] (TODO backport to docs repo) Fix description of lock
 status values

---
 src/Locks.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/Locks.ts b/src/Locks.ts
index 0672c612..3bcdde09 100644
--- a/src/Locks.ts
+++ b/src/Locks.ts
@@ -377,7 +377,7 @@ export default class Locks extends EventEmitter<LocksEventMap> {
    *
    * |_. 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 |
+   * | status | The lock "status":#states of the event. Will be one of @locked@, @unlocked@ or @pending@. | 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 |

From e0c31fea668e9671922dff0a929d73f47a64bcc1 Mon Sep 17 00:00:00 2001
From: Lawrence Forooghian <lawrence@forooghian.com>
Date: Wed, 27 Sep 2023 09:43:19 -0300
Subject: [PATCH 17/30] (TODO backport to docs repo) Fix documentation:
 "instance" refers to Space class

---
 src/Spaces.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/Spaces.ts b/src/Spaces.ts
index 2e7eaddb..6dbbb0ae 100644
--- a/src/Spaces.ts
+++ b/src/Spaces.ts
@@ -108,7 +108,7 @@ class Spaces {
    * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/content/spaces/cursors.textile?plain=1#L108-L122) -->
    * h2(#options). Cursor options
    *
-   * Cursor options are set when creating or retrieving a @space@ instance. They are used to control the behavior of live cursors.
+   * 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:
    *

From 9d24f6ad7532f81f8ded9079ae3c902a6c741f42 Mon Sep 17 00:00:00 2001
From: Lawrence Forooghian <lawrence@forooghian.com>
Date: Wed, 20 Sep 2023 14:27:17 -0300
Subject: [PATCH 18/30] Add class-definitions.md documentation as TSDoc
 comments

Copied all documentation from that document to appropriate places in code.
---
 src/Cursors.ts   | 107 +++++++++++++++++++++++++
 src/Locations.ts |  97 ++++++++++++++++++++++
 src/Locks.ts     | 156 ++++++++++++++++++++++++++++++++++++
 src/Members.ts   | 141 ++++++++++++++++++++++++++++++++
 src/Space.ts     |  86 ++++++++++++++++++++
 src/Spaces.ts    |  69 ++++++++++++++++
 src/types.ts     | 203 +++++++++++++++++++++++++++++++++++++++++++++++
 7 files changed, 859 insertions(+)

diff --git a/src/Cursors.ts b/src/Cursors.ts
index ab300c90..f228953f 100644
--- a/src/Cursors.ts
+++ b/src/Cursors.ts
@@ -47,6 +47,13 @@ const CURSORS_CHANNEL_TAG = '::$cursors';
  *
  * The channel is only created when a member calls @space.cursors.set()@. The live cursors channel object can be accessed through @space.cursors.channel@. To monitor the "underlying state of the cursors channel":/channels#states, the channel object can be accessed through @space.cursors.channel@.
  * <!-- END WEBSITE DOCUMENTATION -->
+ *
+ * > **Documentation source**
+ * >
+ * > The following documentation is copied from `docs/class-definitions.md`.
+ * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
+ * Handles tracking of member cursors within a space. Inherits from [EventEmitter](/docs/usage.md#event-emitters).
+ * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
  */
 export default class Cursors extends EventEmitter<CursorsEventMap> {
   private readonly cursorBatching: CursorBatching;
@@ -136,6 +143,27 @@ export default class Cursors extends EventEmitter<CursorsEventMap> {
    * | 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 |
    * <!-- END WEBSITE DOCUMENTATION -->
+   *
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from `docs/class-definitions.md`.
+   * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
+   * Set the position of a cursor. If a member has not yet entered the space, this method will error.
+   *
+   * A event payload returned contains an object with 2 properties. `position` is an object with 2 required properties, `x` and `y`. These represent the position of the cursor on a 2D plane. A second optional property, `data` can also be passed. This is an object of any shape and is meant for data associated with the cursor movement (like drag or hover calculation results):
+   *
+   * ```ts
+   * type set = (update: { position: CursorPosition, data?: CursorData }) => void;
+   * ```
+   *
+   * Example usage:
+   *
+   * ```ts
+   * window.addEventListener('mousemove', ({ clientX, clientY }) => {
+   *   space.cursors.set({ position: { x: clientX, y: clientY }, data: { color: "red" } });
+   * });
+   * ```
+   * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
    */
   async set(cursor: Pick<CursorUpdate, 'position' | 'data'>) {
     const self = await this.space.members.getSelf();
@@ -210,6 +238,23 @@ export default class Cursors extends EventEmitter<CursorsEventMap> {
    * });
    * ```
    * <!-- END WEBSITE DOCUMENTATION -->
+   *
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from `docs/class-definitions.md`.
+   * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
+   * Listen to `CursorUpdate` events. See [EventEmitter](/docs/usage.md#event-emitters) for overloaded usage.
+   *
+   * Available events:
+   *
+   * - ##### **update**
+   *
+   *   Emits an event when a new cursor position is set. The argument supplied to the event listener is a [CursorUpdate](#cursorupdate).
+   *
+   *   ```ts
+   *   space.cursors.subscribe('update', (cursorUpdate: CursorUpdate) => {});
+   *   ```
+   * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
    */
   subscribe<K extends keyof CursorsEventMap>(
     eventOrEvents: K | K[],
@@ -260,6 +305,17 @@ export default class Cursors extends EventEmitter<CursorsEventMap> {
    * space.cursors.unsubscribe();
    * ```
    * <!-- END WEBSITE DOCUMENTATION -->
+   *
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from `docs/class-definitions.md`.
+   * <!-- 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.
+   *
+   * ```ts
+   * space.cursors.unsubscribe('update');
+   * ```
+   * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
    */
   unsubscribe<K extends keyof CursorsEventMap>(
     eventOrEvents: K | K[],
@@ -293,6 +349,23 @@ export default class Cursors extends EventEmitter<CursorsEventMap> {
   /**
    * <!-- This is to avoid duplication of the website documentation. -->
    * See the documentation for {@link getAll}.
+   *
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from `docs/class-definitions.md`.
+   * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
+   * Get the last `CursorUpdate` object for self.
+   *
+   * ```ts
+   * type getSelf = () => Promise<CursorUpdate | null>;
+   * ```
+   *
+   * Example:
+   *
+   * ```ts
+   * const selfPosition = await space.cursors.getSelf();
+   * ```
+   * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
    */
   async getSelf(): Promise<CursorUpdate | null> {
     const self = await this.space.members.getSelf();
@@ -305,6 +378,23 @@ export default class Cursors extends EventEmitter<CursorsEventMap> {
   /**
    * <!-- This is to avoid duplication of the website documentation. -->
    * See the documentation for {@link getAll}.
+   *
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from `docs/class-definitions.md`.
+   * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
+   * Get the last `CursorUpdate` object for everyone else but yourself.
+   *
+   * ```ts
+   * type getOthers = () => Promise<Record<string, CursorUpdate | null>>;
+   * ```
+   *
+   * Example:
+   *
+   * ```ts
+   * const otherPositions = await space.cursors.getOthers();
+   * ```
+   * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
    */
   async getOthers(): Promise<Record<string, null | CursorUpdate>> {
     const self = await this.space.members.getSelf();
@@ -408,6 +498,23 @@ export default class Cursors extends EventEmitter<CursorsEventMap> {
    * }
    * ```
    * <!-- END WEBSITE DOCUMENTATION -->
+   *
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from `docs/class-definitions.md`.
+   * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
+   * Get the last `CursorUpdate` object for all the members.
+   *
+   * ```ts
+   * type getAll = () => Promise<Record<string, CursorUpdate | null>>;
+   * ```
+   *
+   * Example:
+   *
+   * ```ts
+   * const allLatestPositions = await space.cursors.getAll();
+   * ```
+   * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
    */
   async getAll(): Promise<Record<string, null | CursorUpdate>> {
     const channel = this.getChannel();
diff --git a/src/Locations.ts b/src/Locations.ts
index 7764f991..99c6fedb 100644
--- a/src/Locations.ts
+++ b/src/Locations.ts
@@ -38,6 +38,13 @@ export interface LocationsEventMap {
  *
  * Member locations build upon the functionality of the Pub/Sub Channels "presence":/presence-occupancy/presence feature. Members are entered into the presence set when they "enter the space":/spaces/space#enter.
  * <!-- END WEBSITE DOCUMENTATION -->
+ *
+ * > **Documentation source**
+ * >
+ * > The following documentation is copied from `docs/class-definitions.md`.
+ * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
+ * Handles the tracking of member locations within a space. Inherits from [EventEmitter](/docs/usage.md#event-emitters).
+ * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
  */
 export default class Locations extends EventEmitter<LocationsEventMap> {
   private lastLocationUpdate: Record<string, PresenceMember['data']['locationUpdate']['id']> = {};
@@ -93,6 +100,17 @@ export default class Locations extends EventEmitter<LocationsEventMap> {
    * await space.locations.set({ slide: '3', component: 'slide-title' });
    * ```
    * <!-- END WEBSITE DOCUMENTATION -->
+   *
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from `docs/class-definitions.md`.
+   * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
+   * 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
+   * type set = (update: Location) => Promise<void>;
+   * ```
+   * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
    */
   async set(location: unknown) {
     const self = await this.space.members.getSelf();
@@ -174,6 +192,23 @@ export default class Locations extends EventEmitter<LocationsEventMap> {
    * <p>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, "space state":/spaces/space can be subscribed to which returns an array of all members with their latest state every time any event is triggered.</p>
    * </aside>
    * <!-- END WEBSITE DOCUMENTATION -->
+   *
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from `docs/class-definitions.md`.
+   * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
+   * Listen to events for locations. See [EventEmitter](/docs/usage.md#event-emitters) for overloaded usage.
+   *
+   * Available events:
+   *
+   * - ##### **update**
+   *
+   *   Fires when a member updates their location. The argument supplied to the event listener is a [LocationUpdate](#locationupdate-1).
+   *
+   *   ```ts
+   *   space.locations.subscribe('update', (locationUpdate: LocationUpdate) => {});
+   *   ```
+   * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
    */
   subscribe<K extends keyof LocationsEventMap>(
     eventOrEvents: K | K[],
@@ -216,6 +251,17 @@ export default class Locations extends EventEmitter<LocationsEventMap> {
    * space.locations.unsubscribe();
    * ```
    * <!-- END WEBSITE DOCUMENTATION -->
+   *
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from `docs/class-definitions.md`.
+   * <!-- 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.
+   *
+   * ```ts
+   * space.locations.unsubscribe('update');
+   * ```
+   * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
    */
   unsubscribe<K extends keyof LocationsEventMap>(
     eventOrEvents: K | K[],
@@ -242,6 +288,23 @@ export default class Locations extends EventEmitter<LocationsEventMap> {
   /**
    * <!-- This is to avoid duplication of the website documentation. -->
    * See the documentation for {@link getAll}.
+   *
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from `docs/class-definitions.md`.
+   * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
+   * Get location for self.
+   *
+   * ```ts
+   * type getSelf = () => Promise<Location>;
+   * ```
+   *
+   * Example:
+   *
+   * ```ts
+   * const myLocation = await space.locations.getSelf();
+   * ```
+   * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
    */
   async getSelf(): Promise<unknown> {
     const self = await this.space.members.getSelf();
@@ -251,6 +314,23 @@ export default class Locations extends EventEmitter<LocationsEventMap> {
   /**
    * <!-- This is to avoid duplication of the website documentation. -->
    * See the documentation for {@link getAll}.
+   *
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from `docs/class-definitions.md`.
+   * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
+   * Get location for other members
+   *
+   * ```ts
+   * type getOthers = () => Promise<Record<ConnectionId, Location>>;
+   * ```
+   *
+   * Example:
+   *
+   * ```ts
+   * const otherLocations = await space.locations.getOthers()
+   * ```
+   * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
    */
   async getOthers(): Promise<Record<string, unknown>> {
     const members = await this.space.members.getOthers();
@@ -329,6 +409,23 @@ export default class Locations extends EventEmitter<LocationsEventMap> {
    * }
    * ```
    * <!-- END WEBSITE DOCUMENTATION -->
+   *
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from `docs/class-definitions.md`.
+   * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
+   * Get location for all members.
+   *
+   * ```ts
+   * type getAll = () => Promise<Record<ConnectionId, Location>>;
+   * ```
+   *
+   * 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();
diff --git a/src/Locks.ts b/src/Locks.ts
index 3bcdde09..b6ed1120 100644
--- a/src/Locks.ts
+++ b/src/Locks.ts
@@ -8,6 +8,18 @@ import EventEmitter, { InvalidArgumentError, inspect, type EventListener } from
 
 import SpaceUpdate from './SpaceUpdate.js';
 
+/**
+ * > **Documentation source**
+ * >
+ * > The following documentation is copied from `docs/class-definitions.md`.
+ * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
+ * Additional attributes that can be set when acquiring a lock.
+ *
+ * ```ts
+ * type LockAttributes = Map<string, string>;
+ * ```
+ * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
+ */
 export class LockAttributes extends Map<string, string> {
   toJSON() {
     return Object.fromEntries(this);
@@ -57,6 +69,13 @@ export interface LocksEventMap {
  *
  * Only transitions that result in a @locked@ or @unlocked@ status will emit a lock event that members can "@subscribe()@":#subscribe to.
  * <!-- END WEBSITE DOCUMENTATION -->
+ *
+ * > **Documentation source**
+ * >
+ * > The following documentation is copied from `docs/class-definitions.md`.
+ * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
+ * Provides a mechanism to "lock" a component, reducing the chances of conflict in an application whilst being edited by multiple members. Inherits from [EventEmitter](/docs/usage.md#event-emitters).
+ * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
  */
 export default class Locks extends EventEmitter<LocksEventMap> {
   // locks tracks the local state of locks, which is used to determine whether
@@ -101,6 +120,24 @@ export default class Locks extends EventEmitter<LocksEventMap> {
    *
    * If the lock is not currently held by a member, @get()@ will return @undefined@. Otherwise it will return the most recent lock event for the lock.
    * <!-- END WEBSITE DOCUMENTATION -->
+   *
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from `docs/class-definitions.md`.
+   * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
+   * Get a lock by its id.
+   *
+   * ```ts
+   * type get = (lockId: string) => Lock | undefined
+   * ```
+   *
+   * Example:
+   *
+   * ```ts
+   * const id = "/slide/1/element/3";
+   * const lock = space.locks.get(id);
+   * ```
+   * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
    */
   get(id: string): Lock | undefined {
     const locks = this.locks.get(id);
@@ -172,6 +209,23 @@ export default class Locks extends EventEmitter<LocksEventMap> {
    * ]
    * ```
    * <!-- END WEBSITE DOCUMENTATION -->
+   *
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from `docs/class-definitions.md`.
+   * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
+   * Get all locks that have the `locked` status.
+   *
+   * ```ts
+   * type getAll = () => Promise<Lock[]>
+   * ```
+   *
+   * Example:
+   *
+   * ```ts
+   * const locks = await space.locks.getAll();
+   * ```
+   * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
    */
   async getAll(): Promise<Lock[]> {
     const allLocks: Lock[] = [];
@@ -190,6 +244,23 @@ export default class Locks extends EventEmitter<LocksEventMap> {
   /**
    * <!-- This is to avoid duplication of the website documentation. -->
    * See the documentation for {@link getAll}.
+   *
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from `docs/class-definitions.md`.
+   * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
+   * Get all locks belonging to self that have the `locked` status.
+   *
+   * ```ts
+   * type getSelf = () => Promise<Lock[]>
+   * ```
+   *
+   * Example:
+   *
+   * ```ts
+   * const locks = await space.locks.getSelf();
+   * ```
+   * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
    */
   async getSelf(): Promise<Lock[]> {
     const self = await this.space.members.getSelf();
@@ -202,6 +273,23 @@ export default class Locks extends EventEmitter<LocksEventMap> {
   /**
    * <!-- This is to avoid duplication of the website documentation. -->
    * See the documentation for {@link getAll}.
+   *
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from `docs/class-definitions.md`.
+   * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
+   * Get all locks belonging to all members except self that have the `locked` status.
+   *
+   * ```ts
+   * type getOthers = () => Promise<Lock[]>
+   * ```
+   *
+   * Example:
+   *
+   * ```ts
+   * const locks = await space.locks.getOthers();
+   * ```
+   * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
    */
   async getOthers(): Promise<Lock[]> {
     const self = await this.space.members.getSelf();
@@ -250,6 +338,26 @@ export default class Locks extends EventEmitter<LocksEventMap> {
    *
    * Once a member requests a lock by calling @acquire()@, the lock is temporarily in the "pending state":#states. An event will be emitted based on whether the lock request was successful (a status of @locked@) or invalidated (a status of @unlocked@). This can be "subscribed":#subscribe to in order for the client to know whether their lock request was successful or not.
    * <!-- END WEBSITE DOCUMENTATION -->
+   *
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from `docs/class-definitions.md`.
+   * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
+   * Send a request to acquire a lock. Returns a Promise which resolves once the request has been sent. A resolved Promise holds a `pending` [Lock](#lock). An error will be thrown if a lock request with a status of `pending` or `locked` already exists, returning a rejected promise.
+   *
+   * When a lock acquisition by a member is confirmed with the `locked` status, an `update` event will be emitted. Hence to handle lock acquisition, `acquire()` needs to always be used together with `subscribe()`.
+   *
+   * ```ts
+   * type acquire = (lockId: string) => Promise<Lock>;
+   * ```
+   *
+   * Example:
+   *
+   * ```ts
+   * const id = "/slide/1/element/3";
+   * const lockRequest = await space.locks.acquire(id);
+   * ```
+   * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
    */
   async acquire(id: string, opts?: LockOptions): Promise<Lock> {
     const self = await this.space.members.getSelf();
@@ -303,6 +411,24 @@ export default class Locks extends EventEmitter<LocksEventMap> {
    * <p>When a member "leaves":/spaces/space#leave a space, their locks are automatically released.</p>
    * </aside>
    * <!-- END WEBSITE DOCUMENTATION -->
+   *
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from `docs/class-definitions.md`.
+   * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
+   * Releases a previously requested lock.
+   *
+   * ```ts
+   * type release = (lockId: string) => Promise<void>;
+   * ```
+   *
+   * Example:
+   *
+   * ```ts
+   * const id = "/slide/1/element/3";
+   * await space.locks.release(id);
+   * ```
+   * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
    */
   async release(id: string): Promise<void> {
     const self = await this.space.members.getSelf();
@@ -388,6 +514,25 @@ export default class Locks extends EventEmitter<LocksEventMap> {
    * | 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 |
    * <!-- END WEBSITE DOCUMENTATION -->
+   *
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from `docs/class-definitions.md`.
+   * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
+   * Listen to lock events. See [EventEmitter](/docs/usage.md#event-emitters) for overloaded usage.
+   *
+   * Available events:
+   *
+   * - ##### **update**
+   *
+   *   Listen to changes to locks.
+   *
+   *   ```ts
+   *   space.locks.subscribe('update', (lock: Lock) => {})
+   *   ```
+   *
+   *   The argument supplied to the callback is a [Lock](#lock), representing the lock request and it's status.
+   * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
    */
   subscribe<K extends keyof LocksEventMap>(eventOrEvents: K | K[], listener?: EventListener<LocksEventMap, K>): void;
   subscribe(listener?: EventListener<LocksEventMap, keyof LocksEventMap>): void;
@@ -427,6 +572,17 @@ export default class Locks extends EventEmitter<LocksEventMap> {
    * space.locks.unsubscribe();
    * ```
    * <!-- END WEBSITE DOCUMENTATION -->
+   *
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from `docs/class-definitions.md`.
+   * <!-- 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.
+   *
+   * ```ts
+   * space.locks.unsubscribe('update');
+   * ```
+   * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
    */
   unsubscribe<K extends keyof LocksEventMap>(eventOrEvents: K | K[], listener?: EventListener<LocksEventMap, K>): void;
   unsubscribe(listener?: EventListener<LocksEventMap, keyof LocksEventMap>): void;
diff --git a/src/Members.ts b/src/Members.ts
index 8b714d84..18c3505a 100644
--- a/src/Members.ts
+++ b/src/Members.ts
@@ -46,6 +46,13 @@ export interface MembersEventMap {
  *
  * Avatar stacks build upon the functionality of the Pub/Sub Channels "presence":/presence-occupancy/presence feature. Members are entered into the presence set when they "enter the space":/spaces/space#enter.
  * <!-- END WEBSITE DOCUMENTATION -->
+ *
+ * > **Documentation source**
+ * >
+ * > The following documentation is copied from `docs/class-definitions.md`.
+ * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
+ * Handles members within a space.
+ * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
  */
 class Members extends EventEmitter<MembersEventMap> {
   private lastMemberUpdate: Record<string, PresenceMember['data']['profileUpdate']['id']> = {};
@@ -88,6 +95,23 @@ class Members extends EventEmitter<MembersEventMap> {
   /**
    * <!-- This is to avoid duplication of the website documentation. -->
    * See the documentation for {@link getAll}.
+   *
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from `docs/class-definitions.md`.
+   * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
+   * 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<SpaceMember | null>;
+   * ```
+   *
+   * Example:
+   *
+   * ```ts
+   * const myMember = await space.members.getSelf();
+   * ```
+   * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
    */
   async getSelf(): Promise<SpaceMember | null> {
     return this.space.connectionId ? await this.getByConnectionId(this.space.connectionId) : null;
@@ -221,6 +245,23 @@ class Members extends EventEmitter<MembersEventMap> {
    * ]
    * ```
    * <!-- END WEBSITE DOCUMENTATION -->
+   *
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from `docs/class-definitions.md`.
+   * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
+   * Returns a Promise which resolves to an array of all [SpaceMember](#spacemember) objects (members) currently in the space, including any who have left and not yet timed out. (_see: [offlineTimeout](#spaceoptions)_)
+   *
+   * ```ts
+   * type getAll = () => Promise<SpaceMember[]>;
+   * ```
+   *
+   * Example:
+   *
+   * ```ts
+   * const allMembers = await space.members.getAll();
+   * ```
+   * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
    */
   async getAll(): Promise<SpaceMember[]> {
     const presenceMembers = await this.space.channel.presence.get();
@@ -231,6 +272,23 @@ class Members extends EventEmitter<MembersEventMap> {
   /**
    * <!-- This is to avoid duplication of the website documentation. -->
    * See the documentation for {@link getAll}.
+   *
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from `docs/class-definitions.md`.
+   * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
+   * Returns a Promise which resolves to an array of all [SpaceMember](#spacemember) objects (members) currently in the space, excluding your own member object.
+   *
+   * ```ts
+   * type getSelf = () => Promise<SpaceMember[]>;
+   * ```
+   *
+   * Example:
+   *
+   * ```ts
+   * const otherMembers = await space.members.getOthers();
+   * ```
+   * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
    */
   async getOthers(): Promise<SpaceMember[]> {
     const members = await this.getAll();
@@ -318,6 +376,71 @@ class Members extends EventEmitter<MembersEventMap> {
    * <p>Avatar stack subscription listeners only trigger on events related to members' online status and profile updates. Each event only contains the payload of the member that triggered it. Alternatively, "space state":/spaces/space can be subscribed to which returns an array of all members with their latest state every time any event is triggered.</p>
    * </aside>
    * <!-- END WEBSITE DOCUMENTATION -->
+   *
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from `docs/class-definitions.md`.
+   * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
+   * Listen to member events for the space. See [EventEmitter](/docs/usage.md#event-emitters) for overloaded usage.
+   *
+   * The argument supplied to the callback is the [SpaceMember](#spacemember) object representing the member that triggered the event.
+   *
+   * Example:
+   *
+   * ```ts
+   * space.members.subscribe((member: SpaceMember) => {});
+   * ```
+   *
+   * Available events:
+   *
+   * - ##### **enter**
+   *
+   *   Listen to enter events of members.
+   *
+   *   ```ts
+   *   space.members.subscribe('enter', (member: SpaceMember) => {})
+   *   ```
+   *   The argument supplied to the callback is a [SpaceMember](#spacemember) object representing the member entering the space.
+   *
+   * - ##### **leave**
+   *
+   *   Listen to leave events of members. The leave event will be issued when a member calls `space.leave()` or is disconnected.
+   *
+   *   ```ts
+   *   space.members.subscribe('leave', (member: SpaceMember) => {})
+   *   ```
+   *
+   *   The argument supplied to the callback is a [SpaceMember](#spacemember) object representing the member leaving the space.
+   *
+   * - ##### **remove**
+   *
+   *   Listen to remove events of members. The remove event will be triggered when the [offlineTimeout](#spaceoptions) has passed.
+   *
+   *   ```ts
+   *   space.members.subscribe('remove', (member: SpaceMember) => {})
+   *   ```
+   *
+   *   The argument supplied to the callback is a [SpaceMember](#spacemember) object representing the member removed from the space.
+   *
+   * - ##### **updateProfile**
+   *
+   *   Listen to profile update events of members.
+   *
+   *   ```ts
+   *   space.members.subscribe('updateProfile', (member: SpaceMember) => {})
+   *   ```
+   *   The argument supplied to the callback is a [SpaceMember](#spacemember) object representing the member entering the space.
+   *
+   * - ##### **update**
+   *
+   *   Listen to `enter`, `leave`, `updateProfile` and `remove` events.
+   *
+   *   ```ts
+   *   space.members.subscribe('update', (member: SpaceMember) => {})
+   *   ```
+   *
+   *   The argument supplied to the callback is a [SpaceMember](#spacemember) object representing the member affected by the change.
+   * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
    */
   subscribe<K extends keyof MembersEventMap>(
     eventOrEvents: K | K[],
@@ -366,6 +489,24 @@ class Members extends EventEmitter<MembersEventMap> {
    * space.members.unsubscribe();
    * ```
    * <!-- END WEBSITE DOCUMENTATION -->
+   *
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from `docs/class-definitions.md`.
+   * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
+   * Remove all the event listeners or specific listeners. See [EventEmitter](/docs/usage.md#event-emitters) for detailed usage.
+   *
+   * ```ts
+   * // Unsubscribe from all events
+   * space.members.unsubscribe();
+   *
+   * // Unsubscribe from enter events
+   * space.members.unsubscribe('enter');
+   *
+   * // Unsubscribe from leave events
+   * space.members.unsubscribe('leave');
+   * ```
+   * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
    */
   unsubscribe<K extends keyof MembersEventMap>(
     eventOrEvents: K | K[],
diff --git a/src/Space.ts b/src/Space.ts
index 71f92a1b..4d14b3e0 100644
--- a/src/Space.ts
+++ b/src/Space.ts
@@ -54,13 +54,56 @@ export interface SpaceEventMap {
  *
  * To subscribe to any events in a space, you first need to create or retrieve a space.
  * <!-- END WEBSITE DOCUMENTATION -->
+ *
+ * > **Documentation source**
+ * >
+ * > The following documentation is copied from `docs/class-definitions.md`.
+ * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
+ * An instance of a Space created using [spaces.get](#get). Inherits from [EventEmitter](/docs/usage.md#event-emitters).
+ * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
  */
 class Space extends EventEmitter<SpaceEventMap> {
   private readonly channelName: string;
   readonly connectionId: string | undefined;
   readonly options: SpaceOptions;
+  /**
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from `docs/class-definitions.md`.
+   * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
+   * An instance of [Locations](#locations).
+   *
+   * ```ts
+   * type locations = instanceof Locations;
+   * ```
+   * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
+   */
   readonly locations: Locations;
+  /**
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from `docs/class-definitions.md`.
+   * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
+   * An instance of [Cursors](#cursors).
+   *
+   * ```ts
+   * type cursors = instanceof Cursors;
+   * ```
+   * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
+   */
   readonly cursors: Cursors;
+  /**
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from `docs/class-definitions.md`.
+   * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
+   * An instance of [Members](#members).
+   *
+   * ```ts
+   * type members = instanceof Members;
+   * ```
+   * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
+   */
   readonly members: Members;
   readonly channel: Types.RealtimeChannelPromise;
   readonly locks: Locks;
@@ -165,6 +208,17 @@ class Space extends EventEmitter<SpaceEventMap> {
    * });
    * ```
    * <!-- END WEBSITE DOCUMENTATION -->
+   *
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from `docs/class-definitions.md`.
+   * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
+   * 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
+   * type enter = (profileData?: Record<string, unknown>) => Promise<SpaceMember[]>;
+   * ```
+   * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
    */
   async enter(profileData: ProfileData = null): Promise<SpaceMember[]> {
     return new Promise((resolve) => {
@@ -209,6 +263,27 @@ class Space extends EventEmitter<SpaceEventMap> {
    * });
    * ```
    * <!-- END WEBSITE DOCUMENTATION -->
+   *
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from `docs/class-definitions.md`.
+   * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
+   * Update `profileData`. This data can be an arbitrary JSON-serializable object which is attached to the [member object](#spacemember). If the connection
+   * has not entered the space, calling `updateProfileData` will call `enter` instead.
+   *
+   * ```ts
+   * type updateProfileData = (profileDataOrUpdateFn?: unknown| (unknown) => unknown) => Promise<void>;
+   * ```
+   *
+   * A function can also be passed in. This function will receive the existing `profileData` and lets you update based on the existing value of `profileData`:
+   *
+   * ```ts
+   * await space.updateProfileData((oldProfileData) => {
+   *   const newProfileData = getNewProfileData();
+   *   return { ...oldProfileData, ...newProfileData };
+   * })
+   * ```
+   * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
    */
   async updateProfileData(profileDataOrUpdateFn: ProfileData | ((update: ProfileData) => ProfileData)): Promise<void> {
     const self = await this.members.getSelf();
@@ -247,6 +322,17 @@ class Space extends EventEmitter<SpaceEventMap> {
    *
    * Members will implicitly leave a space after 15 seconds if they abruptly disconnect. If experiencing network disruption, and they reconnect within 15 seconds, then they will remain part of the space and no @leave@ event will be emitted.
    * <!-- END WEBSITE DOCUMENTATION -->
+   *
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from `docs/class-definitions.md`.
+   * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
+   * Leave the space. Can optionally take `profileData`. This triggers the `leave` event, but does not immediately remove the member from the space. See [offlineTimeout](#spaceoptions).
+   *
+   * ```ts
+   * type leave = (profileData?: Record<string, unknown>) => Promise<void>;
+   * ```
+   * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
    */
   async leave(profileData: ProfileData = null) {
     const self = await this.members.getSelf();
diff --git a/src/Spaces.ts b/src/Spaces.ts
index 6dbbb0ae..ac998399 100644
--- a/src/Spaces.ts
+++ b/src/Spaces.ts
@@ -14,11 +14,69 @@ export interface ClientWithOptions extends Types.RealtimePromise {
 
 class Spaces {
   private spaces: Record<string, Space> = {};
+  /**
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from `docs/class-definitions.md`.
+   * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
+   * Instance of the [Ably-JS](https://github.com/ably/ably-js#introduction) client that was passed to the [constructor](#constructor).
+   *
+   * ```ts
+   * type client = Ably.RealtimePromise;
+   * ```
+   * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
+   */
   client: Types.RealtimePromise;
+  /**
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from `docs/class-definitions.md`.
+   * <!-- 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).
+   *
+   * ```ts
+   * type connection = Ably.ConnectionPromise;
+   * ```
+   * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
+   */
   connection: Types.ConnectionPromise;
 
+  /**
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from `docs/class-definitions.md`.
+   * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
+   * Version of the Spaces library.
+   *
+   * ```ts
+   * type version = string;
+   * ```
+   * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
+   */
   readonly version = '0.1.3';
 
+  /**
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from `docs/class-definitions.md`.
+   * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
+   * Create a new instance of the Space SDK by passing an instance of the realtime, promise-based [Ably client](https://github.com/ably/ably-js):
+   *
+   * ```ts
+   * import { Realtime } from 'ably/promise';
+   * import Spaces from '@ably/spaces';
+   *
+   * const client = new Realtime.Promise({ key: "<API-key>", clientId: "<client-ID>" });
+   * const spaces = new Spaces(client);
+   * ```
+   *
+   * Please note that a [clientId](https://ably.com/docs/auth/identified-clients?lang=javascript) is required.
+   *
+   * An API key will required for [basic authentication](https://ably.com/docs/auth/basic?lang=javascript). We strongly recommended that you use [token authentication](https://ably.com/docs/realtime/authentication#token-authentication) in any production environments.
+   *
+   * Refer to the [Ably docs for the JS SDK](https://ably.com/docs/getting-started/setup?lang=javascript) for information on setting up a realtime promise client.
+   * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
+   */
   constructor(client: Types.RealtimePromise) {
     this.client = client;
     this.connection = client.connection;
@@ -122,6 +180,17 @@ class Spaces {
    *
    * The volume of messages sent can be high when using live cursors. Because of this, the last known position of every members' cursor is obtained from "history":/storage-history/history. The @paginationLimit@ is the number of pages that should be searched to find the last position of each cursor. The default is 5.
    * <!-- END WEBSITE DOCUMENTATION -->
+   *
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from `docs/class-definitions.md`.
+   * <!-- 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.
+   *
+   * ```ts
+   * type get = (name: string, options?: SpaceOptions) => Promise<Space>;
+   * ```
+   * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
    */
   async get(name: string, options?: Subset<SpaceOptions>): Promise<Space> {
     if (typeof name !== 'string' || name.length === 0) {
diff --git a/src/types.ts b/src/types.ts
index 96a16ba7..63968b9f 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -1,18 +1,92 @@
 import { Types } from 'ably';
 import type { LockAttributes } from './Locks.js';
 
+/**
+ * > **Documentation source**
+ * >
+ * > The following documentation is copied from `docs/class-definitions.md`.
+ * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
+ * ```ts
+ * type CursorsOptions = {
+ *   outboundBatchInterval?: number;
+ *   paginationLimit?: number;
+ * };
+ * ```
+ * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
+ */
 export interface CursorsOptions {
+  /**
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from `docs/class-definitions.md`.
+   * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
+   * The interval in milliseconds at which a batch of cursor positions are published. This is multiplied by the number of members in the space minus 1. The default value is 25ms.
+   * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
+   */
   outboundBatchInterval: number;
+  /**
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from `docs/class-definitions.md`.
+   * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
+   * The number of pages searched from [history](https://ably.com/docs/storage-history/history) for the last published cursor position. The default is 5.
+   * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
+   */
   paginationLimit: number;
 }
 
+/**
+ * > **Documentation source**
+ * >
+ * > The following documentation is copied from `docs/class-definitions.md`.
+ * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
+ * Represents a cursors position.
+ *
+ * ```ts
+ * type CursorPosition = {
+ *   x: number;
+ *   y: number;
+ * };
+ * ```
+ * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
+ */
 export interface CursorPosition {
   x: number;
   y: number;
 }
 
+/**
+ * > **Documentation source**
+ * >
+ * > The following documentation is copied from `docs/class-definitions.md`.
+ * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
+ * Represent data that can be associated with a cursor update.
+ *
+ * ```ts
+ * type CursorData = Record<string, unknown>;
+ * ```
+ * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
+ */
 export type CursorData = Record<string, unknown>;
 
+/**
+ * > **Documentation source**
+ * >
+ * > The following documentation is copied from `docs/class-definitions.md`.
+ * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
+ * Represents an update to a cursor.
+ *
+ * ```ts
+ * type CursorUpdate = {
+ *   name: string;
+ *   clientId: string;
+ *   connectionId: string;
+ *   position: CursorPosition;
+ *   data?: CursorData;
+ * };
+ * ```
+ * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
+ */
 export interface CursorUpdate {
   clientId: string;
   connectionId: string;
@@ -20,19 +94,117 @@ export interface CursorUpdate {
   data?: CursorData;
 }
 
+/**
+ * > **Documentation source**
+ * >
+ * > The following documentation is copied from `docs/class-definitions.md`.
+ * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
+ * Used to configure a Space instance on creation.
+ *
+ * ```ts
+ * type SpaceOptions = {
+ *   offlineTimeout?: number;
+ *   cursors?: CursorsOptions;
+ * };
+ * ```
+ * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
+ */
 export interface SpaceOptions {
+  /**
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from `docs/class-definitions.md`.
+   * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
+   * Number of milliseconds after a user loses connection or closes their browser window to wait before their [SpaceMember](#spacemember) object is removed from the members list. The default is 120000ms (2 minutes).
+   * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
+   */
   offlineTimeout: number;
+  /**
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from `docs/class-definitions.md`.
+   * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
+   * Options relating to configuring the cursors API (see below).
+   * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
+   */
   cursors: CursorsOptions;
 }
 
 export type ProfileData = Record<string, unknown> | null;
 
+/**
+ * > **Documentation source**
+ * >
+ * > The following documentation is copied from `docs/class-definitions.md`.
+ * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
+ * A SpaceMember represents a member within a Space instance. Each new connection that enters will create a new member, even if they have the same [`clientId`](https://ably.com/docs/auth/identified-clients?lang=javascript).
+ *
+ * ```ts
+ * type SpaceMember = {
+ *   clientId: string;
+ *   connectionId: string;
+ *   isConnected: boolean;
+ *   profileData: Record<string, unknown>;
+ *   location: Location;
+ *   lastEvent: PresenceEvent;
+ * };
+ * ```
+ * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
+ */
 export interface SpaceMember {
+  /**
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from `docs/class-definitions.md`.
+   * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
+   * The client identifier for the user, provided to the ably client instance.
+   * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
+   */
   clientId: string;
+  /**
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from `docs/class-definitions.md`.
+   * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
+   * Identifier for the connection used by the user. This is a unique identifier.
+   * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
+   */
   connectionId: string;
+  /**
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from `docs/class-definitions.md`.
+   * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
+   * Whether the user is connected to Ably.
+   * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
+   */
   isConnected: boolean;
+  /**
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from `docs/class-definitions.md`.
+   * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
+   * Optional user data that can be attached to a user, such as a username or image to display in an avatar stack.
+   * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
+   */
   profileData: ProfileData;
+  /**
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from `docs/class-definitions.md`.
+   * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
+   * The current location of the user within the space.
+   * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
+   */
   location: unknown;
+  /**
+   * > **Documentation source**
+   * >
+   * > The following documentation is copied from `docs/class-definitions.md`.
+   * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
+   * The most recent event emitted by [presence](https://ably.com/docs/presence-occupancy/presence?lang=javascript) and its timestamp. Events will be either `enter`, `leave`, `update` or `present`.
+   * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
+   */
   lastEvent: {
     name: Types.PresenceAction;
     timestamp: number;
@@ -45,8 +217,39 @@ export namespace LockStatuses {
   export type Unlocked = 'unlocked';
 }
 
+/**
+ * > **Documentation source**
+ * >
+ * > The following documentation is copied from `docs/class-definitions.md`.
+ * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
+ * Represents a status of a lock.
+ *
+ * ```ts
+ * type LockStatus = 'pending' | 'locked' | 'unlocked';
+ * ```
+ * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
+ */
 export type LockStatus = LockStatuses.Pending | LockStatuses.Locked | LockStatuses.Unlocked;
 
+/**
+ * > **Documentation source**
+ * >
+ * > The following documentation is copied from `docs/class-definitions.md`.
+ * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
+ * Represents a Lock.
+ *
+ * ```ts
+ * type Lock = {
+ *   id: string;
+ *   status: LockStatus;
+ *   member: SpaceMember;
+ *   timestamp: number;
+ *   attributes?: LockAttributes;
+ *   reason?: Types.ErrorInfo;
+ * };
+ * ```
+ * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
+ */
 export type Lock = {
   id: string;
   status: LockStatus;

From f3b83924d08f0126c0a76896dec73646e1115326 Mon Sep 17 00:00:00 2001
From: Lawrence Forooghian <lawrence@forooghian.com>
Date: Thu, 21 Sep 2023 16:47:02 -0300
Subject: [PATCH 19/30] Split </p> from end of link
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

In an upcoming commit, I’m going to use Pandoc to convert the website
documentation from Textile to Markdown. However, Pandoc’s parser
(incorrectly, I think) thinks that the <p> tag belongs to the link’s
URL, so split it up.
---
 src/Spaces.ts | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/src/Spaces.ts b/src/Spaces.ts
index ac998399..9e401858 100644
--- a/src/Spaces.ts
+++ b/src/Spaces.ts
@@ -156,7 +156,9 @@ class Spaces {
    * ```
    *
    * <aside data-type='note'>
-   * <p>Due to the high frequency at which updates are streamed for cursor movements, live cursors utilizes its own "channel":/channels.</p>
+   * <p>
+   * Due to the high frequency at which updates are streamed for cursor movements, live cursors utilizes its own "channel":/channels.
+   * </p>
    * </aside>
    * <!-- END WEBSITE DOCUMENTATION -->
    *

From bff065b6c59052cfd2ceb60d5716a65de8424257 Mon Sep 17 00:00:00 2001
From: Lawrence Forooghian <lawrence@forooghian.com>
Date: Tue, 26 Sep 2023 16:07:27 -0300
Subject: [PATCH 20/30] Add a script to convert website documentation from
 Textile to Markdown
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

We’ll use this very shortly.
---
 package.json                             |   4 +-
 scripts/convert_website_documentation.ts | 183 +++++++++++++++++++++++
 2 files changed, 185 insertions(+), 2 deletions(-)
 create mode 100644 scripts/convert_website_documentation.ts

diff --git a/package.json b/package.json
index b06ddb0a..623737b3 100644
--- a/package.json
+++ b/package.json
@@ -9,8 +9,8 @@
   "scripts": {
     "lint": "eslint .",
     "lint:fix": "eslint --fix .",
-    "format": "prettier --write --ignore-path .gitignore src demo",
-    "format:check": "prettier --check --ignore-path .gitignore src demo",
+    "format": "prettier --write --ignore-path .gitignore src demo scripts",
+    "format:check": "prettier --check --ignore-path .gitignore src demo scripts",
     "test": "vitest run",
     "test:watch": "vitest watch",
     "coverage": "vitest run --coverage",
diff --git a/scripts/convert_website_documentation.ts b/scripts/convert_website_documentation.ts
new file mode 100644
index 00000000..a79e4807
--- /dev/null
+++ b/scripts/convert_website_documentation.ts
@@ -0,0 +1,183 @@
+import { readdir, lstat, readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { execFile } from 'node:child_process';
+
+async function processDirectory(path: string) {
+  const entries = await readdir(path);
+
+  for (const entry of entries) {
+    const pathToEntry = join(path, entry);
+
+    const stat = await lstat(pathToEntry);
+    if (stat.isDirectory()) {
+      await processDirectory(pathToEntry);
+      continue;
+    }
+
+    if (entry.endsWith('.ts')) {
+      await processFile(pathToEntry);
+    }
+  }
+}
+
+async function processFile(path: string) {
+  console.log(`Processing: ${path}`);
+  const contents = await readFile(path, { encoding: 'utf-8' });
+
+  const beginWebsiteDocumentationRegexp = /<!-- BEGIN WEBSITE DOCUMENTATION \(.*\) -->/g;
+  const endWebsiteDocumentationRegexp = /<!-- END WEBSITE DOCUMENTATION -->/g;
+
+  const lines = contents.split('\n');
+
+  const startLineIndices: number[] = [];
+  const endLineIndices: number[] = [];
+
+  for (const [lineIndex, line] of lines.entries()) {
+    if (beginWebsiteDocumentationRegexp.exec(line)) {
+      startLineIndices.push(lineIndex);
+    }
+    if (endWebsiteDocumentationRegexp.exec(line)) {
+      endLineIndices.push(lineIndex);
+    }
+  }
+
+  for (let documentationIndex = 0; documentationIndex < startLineIndices.length; documentationIndex++) {
+    const startLineIndex = startLineIndices[documentationIndex];
+    const endLineIndex = endLineIndices[documentationIndex];
+
+    const documentation = lines.slice(startLineIndex + 1, endLineIndex).join('\n');
+    const documentationLineCount = endLineIndex - startLineIndex - 1;
+
+    // Convert the documentation comment.
+    const converted = await convertWebsiteDocumentationCommentFragment(documentation);
+
+    // Replace the documentation comment in `lines`.
+    const convertedLines = converted.split('\n');
+    lines.splice(startLineIndex + 1, documentationLineCount, ...convertedLines);
+
+    const addedLinesCount = convertedLines.length - documentationLineCount;
+
+    // Shift the line indices to reflect the length of the converted documentation comment.
+    for (
+      let indexOfDocumentationToShiftLineNumbers = documentationIndex + 1;
+      indexOfDocumentationToShiftLineNumbers < startLineIndices.length;
+      indexOfDocumentationToShiftLineNumbers++
+    ) {
+      startLineIndices[indexOfDocumentationToShiftLineNumbers] += addedLinesCount;
+      endLineIndices[indexOfDocumentationToShiftLineNumbers] += addedLinesCount;
+    }
+  }
+
+  // Write the new contents of the file.
+  const newContents = lines.join('\n');
+  await writeFile(path, newContents, { encoding: 'utf-8' });
+}
+
+async function convertWebsiteDocumentationCommentFragment(commentFragment: string) {
+  const prefixStrippingResult = strippingPrefixOfCommentFragment(commentFragment);
+  const tagged = tagCommentFragmentLines(prefixStrippingResult.content);
+
+  const lines: string[] = [];
+
+  for (const taggedLines of tagged) {
+    switch (taggedLines.type) {
+      case 'textile':
+        lines.push(...(await convertTextileLines(taggedLines.lines)));
+        break;
+      case 'codeBlock':
+        lines.push(...convertCodeBlockLines(taggedLines.lines));
+        break;
+    }
+  }
+
+  return restoringPrefixOfCommentFragment(lines.join('\n'), prefixStrippingResult.prefix);
+}
+
+async function convertTextileLines(textileLines: string[]) {
+  const pandocStdoutPromise = new Promise<string>((resolve, reject) => {
+    const childProcess = execFile(
+      '/opt/homebrew/bin/pandoc',
+      // We choose gfm over commonmark for tables support.
+      ['--from', 'textile', '--to', 'gfm', '--wrap=preserve'],
+      (error, stdout, stderr) => {
+        if (error) {
+          reject(error);
+        } else {
+          resolve(stdout);
+        }
+      },
+    );
+
+    // I don’t fully understand how writing works and whether this always succeeds in writing the full thing; keep an eye out for any weirdness and revisit if necessary.
+    childProcess.stdin!.write(textileLines.join('\n'));
+    childProcess.stdin!.end();
+  });
+
+  const pandocStdout = await pandocStdoutPromise;
+
+  return pandocStdout.split('\n');
+}
+
+function convertCodeBlockLines(codeBlockLines: string[]) {
+  // remove square brackets from language tag
+  const firstLine = codeBlockLines[0].replace(/[[\]]/g, '');
+  return [firstLine, ...codeBlockLines.slice(1)];
+}
+
+type TaggedLines = { type: 'textile' | 'codeBlock'; lines: string[] };
+
+function tagCommentFragmentLines(commentFragment: string) {
+  const lines = commentFragment.split('\n');
+
+  const result: TaggedLines[] = [];
+
+  let current: TaggedLines | null = null;
+
+  for (const line of lines) {
+    if (line.startsWith('```')) {
+      if (current && current.type === 'codeBlock') {
+        // end of code block
+        current.lines.push(line);
+        result.push(current);
+        current = null;
+      } else {
+        if (current) {
+          result.push(current);
+        }
+
+        // start of code block
+        current = { type: 'codeBlock', lines: [line] };
+      }
+    } else {
+      if (current) {
+        current.lines.push(line);
+      } else {
+        current = { type: 'textile', lines: [line] };
+      }
+    }
+  }
+
+  if (current) {
+    result.push(current);
+    current = null;
+  }
+
+  return result;
+}
+
+function strippingPrefixOfCommentFragment(commentFragment: string) {
+  const lines = commentFragment.split('\n');
+  const prefix = /\s+\* /g.exec(lines[0])![0];
+  const newLines = lines.map((line) => line.substring(prefix.length));
+
+  return { content: newLines.join('\n'), prefix };
+}
+
+function restoringPrefixOfCommentFragment(content: string, prefix: string) {
+  const lines = content.split('\n');
+  const newLines = lines.map((line) => `${prefix}${line}`);
+
+  return newLines.join('\n');
+}
+
+processDirectory('src');

From 60d482e6b840e36ed450060c226c108d72ae024f Mon Sep 17 00:00:00 2001
From: Lawrence Forooghian <lawrence@forooghian.com>
Date: Wed, 20 Sep 2023 17:31:17 -0300
Subject: [PATCH 21/30] Convert website documentation from Textile to Markdown

Ran `npx ts-node convert_website_documentation.ts && npm run format`.
---
 src/Cursors.ts   | 135 ++++++++++++++++++++++++++++-------------------
 src/Locations.ts |  94 +++++++++++++++++----------------
 src/Locks.ts     | 128 +++++++++++++++++++++++---------------------
 src/Members.ts   | 112 +++++++++++++++++++++------------------
 src/Space.ts     | 100 +++++++++++++++++++----------------
 src/Spaces.ts    |  67 ++++++++++++-----------
 6 files changed, 347 insertions(+), 289 deletions(-)

diff --git a/src/Cursors.ts b/src/Cursors.ts
index f228953f..f06e3702 100644
--- a/src/Cursors.ts
+++ b/src/Cursors.ts
@@ -26,26 +26,32 @@ const CURSORS_CHANNEL_TAG = '::$cursors';
  *
  * Cursor events are emitted whenever a member moves their mouse within a space. In order to optimize the efficiency and frequency of updates, cursor position events are automatically batched. The batching interval may be customized in order to further optimize for increased performance versus the number of events published.
  *
- * Live cursor updates are not available as part of the "space state":/spaces/space#subscribe and must be subscribed to using "@space.cursors.subscribe()@":#subscribe.
+ * Live cursor updates are not available as part of the [space state](/spaces/space#subscribe) and must be subscribed to using [`space.cursors.subscribe()`](#subscribe).
  *
  * <aside data-type='important'>
- * <p>Live cursors are a great way of providing contextual awareness as to what members are looking at within an application. However, too many cursors moving across a page can often be a distraction rather than an enhancement. As such, Ably recommends a maximum of 20 members simultaneously streaming their cursors in a space at any one time for an optimal end-user experience.</p>
+ * <p>
+ *
+ * Live cursors are a great way of providing contextual awareness as to what members are looking at within an application. However, too many cursors moving across a page can often be a distraction rather than an enhancement. As such, Ably recommends a maximum of 20 members simultaneously streaming their cursors in a space at any one time for an optimal end-user experience.
+ *
+ * </p>
  * </aside>
+ *
  * <!-- END WEBSITE DOCUMENTATION -->
  *
  * > **Documentation source**
  * >
  * > The following documentation is copied from the [Spaces documentation website](https://ably.com/docs/spaces).
  * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/content/spaces/cursors.textile?plain=1#L254-L262) -->
- * h2(#foundations). Live cursor foundations
+ * ## Live cursor 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.
  *
- * 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.
+ * Live cursors build upon the functionality of the Pub/Sub Channels [presence](/presence-occupancy/presence) feature.
  *
- * Live cursors build upon the functionality of the Pub/Sub Channels "presence":/presence-occupancy/presence feature.
+ * Due to the high frequency at which updates are streamed for cursor movements, live cursors utilizes its own [channel](/channels). The other features of the Spaces SDK, such as avatar stacks, member locations and component locking all share a single channel. For this same reason, cursor position updates are not included in the [space state](/spaces/space) and may only be subscribed to on the `cursors` namespace.
  *
- * Due to the high frequency at which updates are streamed for cursor movements, live cursors utilizes its own "channel":/channels. The other features of the Spaces SDK, such as avatar stacks, member locations and component locking all share a single channel. For this same reason, cursor position updates are not included in the "space state":/spaces/space and may only be subscribed to on the @cursors@ namespace.
+ * The channel is only created when a member calls `space.cursors.set()`. The live cursors channel object can be accessed through `space.cursors.channel`. To monitor the [underlying state of the cursors channel](/channels#states), the channel object can be accessed through `space.cursors.channel`.
  *
- * The channel is only created when a member calls @space.cursors.set()@. The live cursors channel object can be accessed through @space.cursors.channel@. To monitor the "underlying state of the cursors channel":/channels#states, the channel object can be accessed through @space.cursors.channel@.
  * <!-- END WEBSITE DOCUMENTATION -->
  *
  * > **Documentation source**
@@ -88,36 +94,58 @@ export default class Cursors extends EventEmitter<CursorsEventMap> {
    * >
    * > The following documentation is copied from the [Spaces documentation website](https://ably.com/docs/spaces).
    * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/content/spaces/cursors.textile?plain=1#L21-L74) -->
-   * Set the position of a member's cursor using the @set()@ method. A position must contain an X-axis value and a Y-axis value to set the cursor position on a 2D plane. Calling @set()@ will emit a cursor event so that other members are informed of the cursor movement in realtime.
+   * Set the position of a member’s cursor using the `set()` method. A position must contain an X-axis value and a Y-axis value to set the cursor position on a 2D plane. Calling `set()` will emit a cursor event so that other members are informed of the cursor movement in realtime.
    *
-   * A member must have been "entered":/spaces/space#enter into the space to set their cursor position.
+   * A member must have been [entered](/spaces/space#enter) into the space to set their cursor position.
    *
-   * The @set()@ method takes the following parameters:
+   * The `set()` method takes the following parameters:
    *
-   * |_. Parameter |_. Description |_. Type |
-   * | 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, such as a color. | Object |
+   * | Parameter  | Description                                                                                                         | Type   |
+   * |------------|---------------------------------------------------------------------------------------------------------------------|--------|
+   * | 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, such as a color. | Object |
    *
    * <aside data-type='note'>
-   * <p>The @data@ parameter can be used to stream additional information related to a cursor's movement, such as:</p>
-   * <ul><li>The color that other member's should display a cursor as.</li>
-   * <li>The ID of an element that a user may be dragging for drag and drop functionality.</li>
-   * <li>Details of any cursor annotations.</li></ul>
-   * <p>Be aware that as live cursor updates are batched it is not advisable to publish data unrelated to cursor position in the @data@ parameter. Use a "pub/sub channel":/channels instead.</p>
+   * <p>
+   *
+   * The `data` parameter can be used to stream additional information related to a cursor’s movement, such as:
+   *
+   * </p>
+   * <ul>
+   * <li>
+   *
+   * The color that other member’s should display a cursor as.
+   *
+   * </li>
+   * <li>
+   *
+   * The ID of an element that a user may be dragging for drag and drop functionality.
+   *
+   * </li>
+   * <li>
+   *
+   * Details of any cursor annotations.
+   *
+   * </li>
+   * </ul>
+   * <p>
+   *
+   * Be aware that as live cursor updates are batched it is not advisable to publish data unrelated to cursor position in the `data` parameter. Use a [pub/sub channel](/channels) instead.
+   *
+   * </p>
    * </aside>
    *
-   * The following is an example of a member setting their cursor position by adding an event listener to obtain their cursor coordinates and then publishing their position using the @set()@ method:
+   * The following is an example of a member setting their cursor position by adding an event listener to obtain their cursor coordinates and then publishing their position using the `set()` method:
    *
-   * ```[javascript]
+   * ```javascript
    * window.addEventListener('mousemove', ({ clientX, clientY }) => {
    *   space.cursors.set({ position: { x: clientX, y: clientY }, data: { color: 'red' } });
    * });
    * ```
+   * The following is an example payload of a cursor event. Cursor events are uniquely identifiable by the `connectionId` of a cursor.
    *
-   * The following is an example payload of a cursor event. Cursor events are uniquely identifiable by the @connectionId@ of a cursor.
-   *
-   * ```[json]
+   * ```json
    * {
    *   "hd9743gjDc": {
    *     "connectionId": "hd9743gjDc",
@@ -132,16 +160,17 @@ 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":/connect. | String |
-   * | clientId | The "client identifier":/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 |
+   * | Property     | Description                                                                                        | Type   |
+   * |--------------|----------------------------------------------------------------------------------------------------|--------|
+   * | connectionId | The unique identifier of the member’s [connection](/connect).                                      | String |
+   * | clientId     | The [client identifier](/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 |
+   *
    * <!-- END WEBSITE DOCUMENTATION -->
    *
    * > **Documentation source**
@@ -224,15 +253,19 @@ export default class Cursors extends EventEmitter<CursorsEventMap> {
    * >
    * > The following documentation is copied from the [Spaces documentation website](https://ably.com/docs/spaces).
    * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/content/spaces/cursors.textile?plain=1#L78-L90) -->
-   * Subscribe to cursor events by registering a listener. Cursor events are emitted whenever a member moves their cursor by calling @set()@. Use the @subscribe()@ method on the @cursors@ object of a space to receive updates.
+   * Subscribe to cursor events by registering a listener. Cursor events are emitted whenever a member moves their cursor by calling `set()`. Use the `subscribe()` method on the `cursors` object of a space to receive updates.
    *
    * <aside data-type='note'>
-   * <p>The rate at which cursor events are published is controlled by the @outboundBatchInterval@ property set in the "cursor options":#options of a space.</p>
+   * <p>
+   *
+   * The rate at which cursor events are published is controlled by the `outboundBatchInterval` property set in the [cursor options](#options) of a space.
+   *
+   * </p>
    * </aside>
    *
    * The following is an example of subscribing to cursor events:
    *
-   * ```[javascript]
+   * ```javascript
    * space.cursors.subscribe('update', (cursorUpdate) => {
    *   console.log(cursorUpdate);
    * });
@@ -295,13 +328,12 @@ export default class Cursors extends EventEmitter<CursorsEventMap> {
    *
    * The following is an example of removing a listener for cursor update events:
    *
-   * ```[javascript]
+   * ```javascript
    * space.cursors.unsubscribe(`update`, listener);
    * ```
-   *
    * Or remove all listeners:
    *
-   * ```[javascript]
+   * ```javascript
    * space.cursors.unsubscribe();
    * ```
    * <!-- END WEBSITE DOCUMENTATION -->
@@ -413,15 +445,14 @@ export default class Cursors extends EventEmitter<CursorsEventMap> {
    * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/content/spaces/cursors.textile?plain=1#L126-L211) -->
    * Cursor positions can be retrieved in one-off calls. These are local calls that retrieve the latest position of cursors retained in memory by the SDK.
    *
-   * The following is an example of retrieving a member's own cursor position:
+   * The following is an example of retrieving a member’s own cursor position:
    *
-   * ```[javascript]
+   * ```javascript
    * const myCursor = await space.cursors.getSelf();
    * ```
+   * The following is an example payload returned by `space.cursors.getSelf()`:
    *
-   * The following is an example payload returned by @space.cursors.getSelf()@:
-   *
-   * ```[json]
+   * ```json
    * {
    *   “clientId”: “DzOBJqgGXzyUBb816Oa6i”,
    *   “connectionId”: “__UJBKZchX”,
@@ -431,16 +462,14 @@ export default class Cursors extends EventEmitter<CursorsEventMap> {
    *   }
    * }
    * ```
-   *
    * The following is an example of retrieving the cursor positions for all members other than the member themselves:
    *
-   * ```[javascript]
+   * ```javascript
    * const othersCursors = await space.cursors.getOthers();
    * ```
+   * The following is an example payload returned by `space.cursors.getOthers()`:
    *
-   * The following is an example payload returned by @space.cursors.getOthers()@:
-   *
-   * ```[json]
+   * ```json
    * {
    *   "3ej3q7yZZz": {
    *       "clientId": "yyXidHatpP3hJpMpXZi8W",
@@ -460,16 +489,14 @@ export default class Cursors extends EventEmitter<CursorsEventMap> {
    *   }
    * }
    * ```
+   * The following is an example of retrieving the cursor positions for all members, including the member themselves. `getAll()` is useful for retrieving the initial position of members’ cursors.
    *
-   * The following is an example of retrieving the cursor positions for all members, including the member themselves. @getAll()@ is useful for retrieving the initial position of members' cursors.
-   *
-   * ```[javascript]
+   * ```javascript
    * const allCursors = await space.cursors.getAll();
    * ```
+   * The following is an example payload returned by `space.cursors.getAll()`:
    *
-   * The following is an example payload returned by @space.cursors.getAll()@:
-   *
-   * ```[json]
+   * ```json
    * {
    *   "3ej3q7yZZz": {
    *       "clientId": "yyXidHatpP3hJpMpXZi8W",
diff --git a/src/Locations.ts b/src/Locations.ts
index 99c6fedb..d5401cb8 100644
--- a/src/Locations.ts
+++ b/src/Locations.ts
@@ -23,20 +23,22 @@ export interface LocationsEventMap {
  * >
  * > The following documentation is copied from the [Spaces documentation website](https://ably.com/docs/spaces).
  * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/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.
+ * 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 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.
  * <!-- END WEBSITE DOCUMENTATION -->
  *
  * > **Documentation source**
  * >
  * > The following documentation is copied from the [Spaces documentation website](https://ably.com/docs/spaces).
  * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/content/spaces/locations.textile?plain=1#L211-L215) -->
- * h2(#foundations). Member location foundations
+ * ## 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.
  *
- * 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](/presence-occupancy/presence) feature. Members are entered into the presence set when they [enter the space](/spaces/space#enter).
  *
- * Member locations build upon the functionality of the Pub/Sub Channels "presence":/presence-occupancy/presence feature. Members are entered into the presence set when they "enter the space":/spaces/space#enter.
  * <!-- END WEBSITE DOCUMENTATION -->
  *
  * > **Documentation source**
@@ -88,15 +90,15 @@ export default class Locations extends EventEmitter<LocationsEventMap> {
    * >
    * > The following documentation is copied from the [Spaces documentation website](https://ably.com/docs/spaces).
    * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/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.
+   * 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.
    *
-   * A member must have been "entered":/spaces/space#enter into the space to set their location.
+   * A member must have been [entered](/spaces/space#enter) into the space to set their location.
    *
-   * 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@.
+   * 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`.
    *
    * The following is an example of a member setting their location to a specific slide number, and element on that slide:
    *
-   * ```[javascript]
+   * ```javascript
    * await space.locations.set({ slide: '3', component: 'slide-title' });
    * ```
    * <!-- END WEBSITE DOCUMENTATION -->
@@ -128,25 +130,28 @@ export default class Locations extends EventEmitter<LocationsEventMap> {
    * >
    * > The following documentation is copied from the [Spaces documentation website](https://ably.com/docs/spaces).
    * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/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 [`set()`](#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 `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`.
    *
    * <aside data-type='note'>
-   * <p> 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.</p>
+   * <p>
+   *
+   * 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.
+   *
+   * </p>
    * </aside>
    *
    * The following is an example of subscribing to location events:
    *
-   * ```[javascript]
+   * ```javascript
    * space.locations.subscribe('update', (locationUpdate) => {
    *   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 @currentLocation@ and @previousLocation@:
-   *
-   * ```[json]
+   * ```json
    * {
    *   "member": {
    *     "clientId": "clemons#142",
@@ -175,22 +180,27 @@ 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":/auth/identified-clients for the member. | String |
-   * | member.connectionId | The unique identifier of the member's "connection":/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.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 |
+   * | Property                   | Description                                                                                                           | Type    |
+   * |----------------------------|-----------------------------------------------------------------------------------------------------------------------|---------|
+   * | member.clientId            | The [client identifier](/auth/identified-clients) for the member.                                                     | String  |
+   * | member.connectionId        | The unique identifier of the member’s [connection](/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.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  |
    *
    * <aside data-type='further-reading'>
-   * <p>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, "space state":/spaces/space can be subscribed to which returns an array of all members with their latest state every time any event is triggered.</p>
+   * <p>
+   *
+   * 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, [space state](/spaces/space) can be subscribed to which returns an array of all members with their latest state every time any event is triggered.
+   *
+   * </p>
    * </aside>
+   *
    * <!-- END WEBSITE DOCUMENTATION -->
    *
    * > **Documentation source**
@@ -241,13 +251,12 @@ export default class Locations extends EventEmitter<LocationsEventMap> {
    *
    * The following is an example of removing a listener for location update events:
    *
-   * ```[javascript]
+   * ```javascript
    * space.locations.unsubscribe('update', listener);
    * ```
-   *
    * Or remove all listeners:
    *
-   * ```[javascript]
+   * ```javascript
    * space.locations.unsubscribe();
    * ```
    * <!-- END WEBSITE DOCUMENTATION -->
@@ -348,30 +357,27 @@ export default class Locations extends EventEmitter<LocationsEventMap> {
    * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/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:
+   * The following is an example of retrieving a member’s own location:
    *
-   * ```[javascript]
+   * ```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`:
    *
-   * The following is an example payload returned by @space.locations.getSelf()@. It will return the properties of the member's @location@:
-   *
-   * ```[json]
+   * ```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]
+   * ```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`:
    *
-   * The following is an example payload returned by @space.locations.getOthers()@: It will return the properties of all member's @location@ by their @connectionId@:
-   *
-   * ```[json]
+   * ```json
    * {
    *   "xG6H3lnrCn": {
    *       "slide": "1",
@@ -383,16 +389,14 @@ export default class Locations extends EventEmitter<LocationsEventMap> {
    *   }
    * }
    * ```
-   *
    * The following is an example of retrieving the location objects of all members, including the member themselves:
    *
-   * ```[javascript]
+   * ```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`:
    *
-   * 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]
+   * ```json
    * {
    *   "xG6H3lnrCn": {
    *       "slide": "1",
diff --git a/src/Locks.ts b/src/Locks.ts
index b6ed1120..60672271 100644
--- a/src/Locks.ts
+++ b/src/Locks.ts
@@ -39,35 +39,45 @@ export interface LocksEventMap {
  * >
  * > The following documentation is copied from the [Spaces documentation website](https://ably.com/docs/spaces).
  * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/content/spaces/locking.textile?plain=1#L9-L37) -->
- * The component locking feature enables members to optimistically lock stateful UI components before editing them. This reduces the chances of conflicting changes being made to the same component by different members. A component could be a cell in a spreadsheet that a member is updating, or an input field on a form they're filling in.
+ * The component locking feature enables members to optimistically lock stateful UI components before editing them. This reduces the chances of conflicting changes being made to the same component by different members. A component could be a cell in a spreadsheet that a member is updating, or an input field on a form they’re filling in.
  *
  * Once a lock has been acquired by a member, the component that it relates to can be updated in the UI to visually indicate to other members that it is locked and and which member has the lock. The component can then be updated once the editing member has released the lock to indicate that it is now unlocked.
  *
- * Each lock is identified by a unique string ID, and only a single member may hold a lock with a given string at any one time. A lock will exist in one of three "states":#states and may only transition between states in specific circumstances.
+ * Each lock is identified by a unique string ID, and only a single member may hold a lock with a given string at any one time. A lock will exist in one of three [states](#states) and may only transition between states in specific circumstances.
  *
  * <aside data-type='important'>
- * <p>Optimistic locking means that there is a chance that two members may begin editing the same UI component before it is confirmed which member holds the lock. On average, the time taken to reconcile which member holds a lock is in the hundreds of milliseconds. Your application needs to handle the member that successfully obtained the lock, as well as the member that had their request invalidated.</p>
+ * <p>
+ *
+ * Optimistic locking means that there is a chance that two members may begin editing the same UI component before it is confirmed which member holds the lock. On average, the time taken to reconcile which member holds a lock is in the hundreds of milliseconds. Your application needs to handle the member that successfully obtained the lock, as well as the member that had their request invalidated.
+ *
+ * </p>
  * </aside>
  *
- * h2(#states). Lock states
+ * ## Lock states
  *
- * Component locking is handled entirely client-side. Members may begin to optimistically edit a component as soon as they call "@acquire()@":#acquire on the lock identifier related to it. Alternatively, you could wait until they receive a @locked@ event and display a spinning symbol in the UI until this is received. In either case a subsequent @unlocked@ event may invalidate that member's lock request if another member acquired it earlier. The time for confirmation of whether a lock request was successful or rejected is, on average, in the hundreds of milliseconds, however your code should handle all possible lock state transitions.
+ * Component locking is handled entirely client-side. Members may begin to optimistically edit a component as soon as they call [`acquire()`](#acquire) on the lock identifier related to it. Alternatively, you could wait until they receive a `locked` event and display a spinning symbol in the UI until this is received. In either case a subsequent `unlocked` event may invalidate that member’s lock request if another member acquired it earlier. The time for confirmation of whether a lock request was successful or rejected is, on average, in the hundreds of milliseconds, however your code should handle all possible lock state transitions.
  *
  * 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.
+ * `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.
  *
  * The following lock state transitions may occur:
  *
- * * None → @pending@: a member calls "@acquire()@":#acquire to request a lock.
- * * @pending@ → @locked@: the requesting member holds the lock.
- * * @pending@ → @unlocked@: the requesting member does not hold the lock, since another member already holds it.
- * * @locked@ → @unlocked@: the lock was either explicitly "released":#release by the member, or their request was invalidated by a concurrent request which took precedence.
- * * @unlocked@ → @locked@: the requesting member reacquired a lock they previously held.
+ * - None → `pending`: a member calls [`acquire()`](#acquire) to request a lock.
+ * - `pending` → `locked`: the requesting member holds the lock.
+ * - `pending` → `unlocked`: the requesting member does not hold the lock, since another member already holds it.
+ * - `locked` → `unlocked`: the lock was either explicitly [released](#release) by the member, or their request was invalidated by a concurrent request which took precedence.
+ * - `unlocked` → `locked`: the requesting member reacquired a lock they previously held.
+ *
+ * Only transitions that result in a `locked` or `unlocked` status will emit a lock event that members can [`subscribe()`](#subscribe) to.
  *
- * Only transitions that result in a @locked@ or @unlocked@ status will emit a lock event that members can "@subscribe()@":#subscribe to.
  * <!-- END WEBSITE DOCUMENTATION -->
  *
  * > **Documentation source**
@@ -97,28 +107,26 @@ export default class Locks extends EventEmitter<LocksEventMap> {
    * >
    * > The following documentation is copied from the [Spaces documentation website](https://ably.com/docs/spaces).
    * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/content/spaces/locking.textile?plain=1#L171-L192) -->
-   * Use the @get()@ method to query whether a lock is currently locked, and by which member if it is. The lock is identifiable by its unique string ID.
+   * Use the `get()` method to query whether a lock is currently locked, and by which member if it is. The lock is identifiable by its unique string ID.
    *
    * The following is an example of checking whether a lock identifier is currently locked:
    *
-   * ```[javascript]
+   * ```javascript
    * const isLocked = space.locks.get(id) !== undefined;
    * ```
-   *
    * The following is an example of checking which member holds the lock:
    *
-   * ```[javascript]
+   * ```javascript
    * const { member } = space.locks.get(id);
    * ```
-   *
    * The following is an example of viewing the attributes assigned to the lock by the member holding it:
    *
-   * ```[javascript]
+   * ```javascript
    * const { request } = space.locks.get(id);
    * const viewLock = request.attributes.get(key);
    * ```
+   * If the lock is not currently held by a member, `get()` will return `undefined`. Otherwise it will return the most recent lock event for the lock.
    *
-   * If the lock is not currently held by a member, @get()@ will return @undefined@. Otherwise it will return the most recent lock event for the lock.
    * <!-- END WEBSITE DOCUMENTATION -->
    *
    * > **Documentation source**
@@ -160,13 +168,12 @@ export default class Locks extends EventEmitter<LocksEventMap> {
    *
    * The following is an example of retrieving an array of all currently held locks in a space:
    *
-   * ```[javascript]
+   * ```javascript
    * const allLocks = await space.locks.getAll();
    * ```
+   * The following is an example payload returned by `space.locks.getAll()`:
    *
-   * The following is an example payload returned by @space.locks.getAll()@:
-   *
-   * ```[json]
+   * ```json
    * [
    *   {
    *     "id": "s1-c2",
@@ -305,27 +312,25 @@ export default class Locks extends EventEmitter<LocksEventMap> {
    * >
    * > The following documentation is copied from the [Spaces documentation website](https://ably.com/docs/spaces).
    * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/content/spaces/locking.textile?plain=1#L41-L72) -->
-   * Use the @acquire()@ method to attempt to acquire a lock with a given unique ID. Additional @attributes@ may be passed when trying to acquire a lock that can contain a set of arbitrary key-value pairs. An example of using @attributes@ is to store the component ID the lock relates to so that it can be easily updated in the UI with a visual indication of its lock status.
+   * Use the `acquire()` method to attempt to acquire a lock with a given unique ID. Additional `attributes` may be passed when trying to acquire a lock that can contain a set of arbitrary key-value pairs. An example of using `attributes` is to store the component ID the lock relates to so that it can be easily updated in the UI with a visual indication of its lock status.
    *
-   * A member must have been "entered":/spaces/space#enter into the space to acquire a lock.
+   * A member must have been [entered](/spaces/space#enter) into the space to acquire a lock.
    *
    * The following is an example of attempting to acquire a lock:
    *
-   * ```[javascript]
+   * ```javascript
    * const acquireLock = await space.locks.acquire(id);
    * ```
+   * The following is an example of passing a set of `attributes` when trying to acquire a lock:
    *
-   * The following is an example of passing a set of @attributes@ when trying to acquire a lock:
-   *
-   * ```[javascript]
+   * ```javascript
    * const lockAttributes = new Map();
    * lockAttributes.set('component', 'cell-d3');
    * const acquireLock = await space.locks.acquire(id, { lockAttributes });
    * ```
+   * The following is an example payload returned by `space.locks.acquire()`. The promise will resolve to a lock request with the `pending` status:
    *
-   * The following is an example payload returned by @space.locks.acquire()@. The promise will resolve to a lock request with the @pending@ status:
-   *
-   * ```[json]
+   * ```json
    * {
    *   "id": "s2-d14",
    *   "status": "pending",
@@ -335,8 +340,8 @@ export default class Locks extends EventEmitter<LocksEventMap> {
    *   }
    * }
    * ```
+   * Once a member requests a lock by calling `acquire()`, the lock is temporarily in the [pending state](#states). An event will be emitted based on whether the lock request was successful (a status of `locked`) or invalidated (a status of `unlocked`). This can be [subscribed](#subscribe) to in order for the client to know whether their lock request was successful or not.
    *
-   * Once a member requests a lock by calling @acquire()@, the lock is temporarily in the "pending state":#states. An event will be emitted based on whether the lock request was successful (a status of @locked@) or invalidated (a status of @unlocked@). This can be "subscribed":#subscribe to in order for the client to know whether their lock request was successful or not.
    * <!-- END WEBSITE DOCUMENTATION -->
    *
    * > **Documentation source**
@@ -397,19 +402,23 @@ export default class Locks extends EventEmitter<LocksEventMap> {
    * >
    * > The following documentation is copied from the [Spaces documentation website](https://ably.com/docs/spaces).
    * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/content/spaces/locking.textile?plain=1#L76-L88) -->
-   * Use the @release()@ method to explicitly release a lock once a member has finished editing the related component. For example, the @release()@ method can be called once a user clicks outside of the component, such as clicking on another cell within a spreadsheet. Any UI indications that the previous cell was locked can then be cleared.
+   * Use the `release()` method to explicitly release a lock once a member has finished editing the related component. For example, the `release()` method can be called once a user clicks outside of the component, such as clicking on another cell within a spreadsheet. Any UI indications that the previous cell was locked can then be cleared.
    *
    * The following is an example of releasing a lock:
    *
-   * ```[javascript]
+   * ```javascript
    * await space.locks.release(id);
    * ```
-   *
-   * Releasing a lock will emit a lock event with a "lock status":#states of @unlocked@.
+   * Releasing a lock will emit a lock event with a [lock status](#states) of `unlocked`.
    *
    * <aside data-type='note'>
-   * <p>When a member "leaves":/spaces/space#leave a space, their locks are automatically released.</p>
+   * <p>
+   *
+   * When a member [leaves](/spaces/space#leave) a space, their locks are automatically released.
+   *
+   * </p>
    * </aside>
+   *
    * <!-- END WEBSITE DOCUMENTATION -->
    *
    * > **Documentation source**
@@ -453,18 +462,17 @@ export default class Locks extends EventEmitter<LocksEventMap> {
    * >
    * > The following documentation is copied from the [Spaces documentation website](https://ably.com/docs/spaces).
    * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/content/spaces/locking.textile?plain=1#L92-L151) -->
-   * Subscribe to lock events by registering a listener. Lock events are emitted whenever the "lock state":#states transitions into @locked@ or @unlocked@. Use the @subscribe()@ method on the @locks@ namespace of the space to receive updates.
+   * Subscribe to lock events by registering a listener. Lock events are emitted whenever the [lock state](#states) transitions into `locked` or `unlocked`. Use the `subscribe()` method on the `locks` namespace of the space to receive updates.
    *
-   * All lock events are @update@ events. When a lock event is received, UI components can be updated to add and remove visual indications of which member is locking them, as well as enabling and disabling the ability for other members to edit them.
+   * All lock events are `update` events. When a lock event is received, UI components can be updated to add and remove visual indications of which member is locking them, as well as enabling and disabling the ability for other members to edit them.
    *
    * The following is an example of subscribing to lock events:
    *
-   * ```[javascript]
+   * ```javascript
    * space.locks.subscribe('update', (lock) => {
    *   console.log(lock);
    * });
    * ```
-   *
    * The following is an example payload of a lock event:
    *
    * ```json
@@ -498,21 +506,22 @@ 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 one of @locked@, @unlocked@ or @pending@. | 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":/auth/identified-clients for the member. | String |
-   * | member.connectionId | The unique identifier of the member's "connection":/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 |
+   * | Property                   | Description                                                                                                                  | Type      |
+   * |----------------------------|------------------------------------------------------------------------------------------------------------------------------|-----------|
+   * | id                         | The unique ID of the lock request.                                                                                           | String    |
+   * | status                     | The lock [status](#states) of the event. Will be one of `locked`, `unlocked` or `pending`.                                   | 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](/auth/identified-clients) for the member.                                                            | String    |
+   * | member.connectionId        | The unique identifier of the member’s [connection](/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    |
+   *
    * <!-- END WEBSITE DOCUMENTATION -->
    *
    * > **Documentation source**
@@ -562,13 +571,12 @@ export default class Locks extends EventEmitter<LocksEventMap> {
    *
    * The following is an example of removing a listener for lock update events:
    *
-   * ```[javascript]
+   * ```javascript
    * space.locks.unsubscribe('update', listener);
    * ```
-   *
    * Or remove all listeners:
    *
-   * ```[javascript]
+   * ```javascript
    * space.locks.unsubscribe();
    * ```
    * <!-- END WEBSITE DOCUMENTATION -->
diff --git a/src/Members.ts b/src/Members.ts
index 18c3505a..b6b2c754 100644
--- a/src/Members.ts
+++ b/src/Members.ts
@@ -20,31 +20,44 @@ export interface MembersEventMap {
  * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/14acea6dee7bf3872a3d32d43732f934cbe93a7d/content/spaces/avatar.textile?plain=1#L9-L24) -->
  * Avatar stacks are the most common way of showing the online status of members in an application by displaying an avatar for each member. Events are emitted whenever a member enters or leaves a space, or updates their profile data. Additional information can also be provided, such as a profile picture and email address.
  *
- * Subscribe to the @space.members@ namespace in order to keep your avatar stack updated in realtime.
+ * Subscribe to the `space.members` namespace in order to keep your avatar stack updated in realtime.
  *
- * h2(#events). Event types
+ * ## Event types
  *
  * 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.
+ * `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.
  *
  * <aside data-type='note'>
- * <p>Members "enter":/spaces/space#enter, "leave":/spaces/space#leave, and "update":/spaces/space#update-profile a "space":/spaces/space directly. The @members@ namespace is used to subscribe to these updates.</p>
+ * <p>
+ *
+ * Members [enter](/spaces/space#enter), [leave](/spaces/space#leave), and [update](/spaces/space#update-profile) a [space](/spaces/space) directly. The `members` namespace is used to subscribe to these updates.
+ *
+ * </p>
  * </aside>
+ *
  * <!-- END WEBSITE DOCUMENTATION -->
  *
  * > **Documentation source**
  * >
  * > The following documentation is copied from the Spaces documentation website.
  * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/14acea6dee7bf3872a3d32d43732f934cbe93a7d/content/spaces/avatar.textile?plain=1#L296-L300) -->
- * h2(#foundations). Avatar stack foundations
+ * ## Avatar stack 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.
+ * 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.
+ *
+ * Avatar stacks build upon the functionality of the Pub/Sub Channels [presence](/presence-occupancy/presence) feature. Members are entered into the presence set when they [enter the space](/spaces/space#enter).
  *
- * Avatar stacks build upon the functionality of the Pub/Sub Channels "presence":/presence-occupancy/presence feature. Members are entered into the presence set when they "enter the space":/spaces/space#enter.
  * <!-- END WEBSITE DOCUMENTATION -->
  *
  * > **Documentation source**
@@ -122,17 +135,16 @@ class Members extends EventEmitter<MembersEventMap> {
    * >
    * > The following documentation is copied from the Spaces documentation website.
    * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/14acea6dee7bf3872a3d32d43732f934cbe93a7d/content/spaces/avatar.textile?plain=1#L128-L249) -->
-   * Space membership can be retrieved in one-off calls. These are local calls and retrieve the membership retained in memory by the SDK. One-off calls to retrieve membership can be used for operations such as displaying a member's own profile data to them, or retrieving a list of all other members to use to "update their profile data":/spaces/space#update-profile.
+   * Space membership can be retrieved in one-off calls. These are local calls and retrieve the membership retained in memory by the SDK. One-off calls to retrieve membership can be used for operations such as displaying a member’s own profile data to them, or retrieving a list of all other members to use to [update their profile data](/spaces/space#update-profile).
    *
-   * The following is an example of retrieving a member's own member object:
+   * The following is an example of retrieving a member’s own member object:
    *
-   * ```[javascript]
+   * ```javascript
    * const myMemberInfo = await space.members.getSelf();
    * ```
+   * The following is an example payload returned by `space.members.getSelf()`:
    *
-   * The following is an example payload returned by @space.members.getSelf()@:
-   *
-   * ```[json]
+   * ```json
    *   {
    *     "clientId": "clemons#142",
    *     "connectionId": "hd9743gjDc",
@@ -148,16 +160,14 @@ class Members extends EventEmitter<MembersEventMap> {
    *     }
    *   }
    * ```
-   *
    * The following is an example of retrieving an array of member objects for all members other than the member themselves. Ths includes members that have recently left the space, but have not yet been removed.
    *
-   * ```[javascript]
+   * ```javascript
    * const othersMemberInfo = await space.members.getOthers();
    * ```
+   * The following is an example payload returned by `space.members.getOthers()`:
    *
-   * The following is an example payload returned by @space.members.getOthers()@:
-   *
-   * ```[json]
+   * ```json
    * [
    *   {
    *     "clientId": "torange#1",
@@ -189,16 +199,14 @@ class Members extends EventEmitter<MembersEventMap> {
    *   }
    * ]
    * ```
-   *
    * The following is an example of retrieving an array of all member objects, including the member themselves. Ths includes members that have recently left the space, but have not yet been removed.
    *
-   * ```[javascript]
+   * ```javascript
    * const allMembers = await space.members.getAll();
    * ```
+   * The following is an example payload returned by `space.members.getAll()`:
    *
-   * The following is an example payload returned by @space.members.getAll()@:
-   *
-   * ```[json]
+   * ```json
    * [
    *   {
    *     "clientId": "clemons#142",
@@ -300,11 +308,11 @@ class Members extends EventEmitter<MembersEventMap> {
    * >
    * > The following documentation is copied from the Spaces documentation website.
    * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/14acea6dee7bf3872a3d32d43732f934cbe93a7d/content/spaces/avatar.textile?plain=1#L28-L102) -->
-   * Subscribe to members' online status and profile updates by registering a listener. Member events are emitted whenever a member "enters":/spaces/space#enter or "leaves":/spaces/space#leave the space, or updates their profile data. Use the @subscribe()@ method on the @members@ object of a space to receive updates.
+   * Subscribe to members’ online status and profile updates by registering a listener. Member events are emitted whenever a member [enters](/spaces/space#enter) or [leaves](/spaces/space#leave) the space, or updates their profile data. Use the `subscribe()` method on the `members` object of a space to receive updates.
    *
    * The following is an example of subscribing to the different member event types:
    *
-   * ```[javascript]
+   * ```javascript
    * // Subscribe to member enters in a space
    * space.members.subscribe('enter', (memberUpdate) => {
    *   console.log(memberUpdate);
@@ -325,26 +333,23 @@ class Members extends EventEmitter<MembersEventMap> {
    *   console.log(memberUpdate);
    * });
    * ```
+   * It’s also possible to subscribe to multiple event types with the same listener by using an array:
    *
-   * It's also possible to subscribe to multiple event types with the same listener by using an array:
-   *
-   * ```[javascript]
+   * ```javascript
    * space.members.subscribe(['enter', 'update'], (memberUpdate) => {
    *   console.log(memberUpdate);
    * });
    * ```
-   *
    * Or subscribe to all event types:
    *
-   * ```[javascript]
+   * ```javascript
    * space.members.subscribe((memberUpdate) => {
    *   console.log(memberUpdate);
    * });
    * ```
+   * The following is an example payload of a member event. The `lastEvent.name` describes which [event type](#events) a payload relates to.
    *
-   * The following is an example payload of a member event. The @lastEvent.name@ describes which "event type":#events a payload relates to.
-   *
-   * ```[json]
+   * ```json
    *   {
    *     "clientId": "clemons#142",
    *     "connectionId": "hd9743gjDc",
@@ -360,21 +365,26 @@ class Members extends EventEmitter<MembersEventMap> {
    *     }
    *   }
    * ```
-   *
    * The following are the properties of a member event payload:
    *
-   * |_. Property |_. Description |_. Type |
-   * | clientId | The "client identifier":/auth/identified-clients for the member. | String |
-   * | connectionId | The unique identifier of the member's "connection":/connect. | String |
-   * | isConnected | Whether the member is connected to Ably or not. | Boolean |
-   * | profileData | The optional "profile data":#profile-data associated with the member. | Object |
-   * | location | The current "location":/spaces/locations of the member. Will be @null@ for @enter@, @leave@ and @remove@ events. | Object |
-   * | lastEvent.name | The most recent event emitted by the member. | String |
-   * | lastEvent.timestamp | The timestamp of the most recently emitted event. | Number |
+   * | Property            | Description                                                                                                       | Type    |
+   * |---------------------|-------------------------------------------------------------------------------------------------------------------|---------|
+   * | clientId            | The [client identifier](/auth/identified-clients) for the member.                                                 | String  |
+   * | connectionId        | The unique identifier of the member’s [connection](/connect).                                                     | String  |
+   * | isConnected         | Whether the member is connected to Ably or not.                                                                   | Boolean |
+   * | profileData         | The optional [profile data](#profile-data) associated with the member.                                            | Object  |
+   * | location            | The current [location](/spaces/locations) of the member. Will be `null` for `enter`, `leave` and `remove` events. | Object  |
+   * | lastEvent.name      | The most recent event emitted by the member.                                                                      | String  |
+   * | lastEvent.timestamp | The timestamp of the most recently emitted event.                                                                 | Number  |
    *
    * <aside data-type='further-reading'>
-   * <p>Avatar stack subscription listeners only trigger on events related to members' online status and profile updates. Each event only contains the payload of the member that triggered it. Alternatively, "space state":/spaces/space can be subscribed to which returns an array of all members with their latest state every time any event is triggered.</p>
+   * <p>
+   *
+   * Avatar stack subscription listeners only trigger on events related to members’ online status and profile updates. Each event only contains the payload of the member that triggered it. Alternatively, [space state](/spaces/space) can be subscribed to which returns an array of all members with their latest state every time any event is triggered.
+   *
+   * </p>
    * </aside>
+   *
    * <!-- END WEBSITE DOCUMENTATION -->
    *
    * > **Documentation source**
@@ -473,19 +483,17 @@ class Members extends EventEmitter<MembersEventMap> {
    *
    * The following is an example of removing a listener for one member event type:
    *
-   * ```[javascript]
+   * ```javascript
    * space.members.unsubscribe('enter', listener);
    * ```
+   * It’s also possible to remove listeners for multiple member event types:
    *
-   * It's also possible to remove listeners for multiple member event types:
-   *
-   * ```[javascript]
+   * ```javascript
    * space.members.unsubscribe(['enter', 'leave'], listener);
    * ```
-   *
    * Or remove all listeners:
    *
-   * ```[javascript]
+   * ```javascript
    * space.members.unsubscribe();
    * ```
    * <!-- END WEBSITE DOCUMENTATION -->
diff --git a/src/Space.ts b/src/Space.ts
index 4d14b3e0..d9d63ebb 100644
--- a/src/Space.ts
+++ b/src/Space.ts
@@ -43,16 +43,17 @@ export interface SpaceEventMap {
  *
  * The following features can be implemented within a space:
  *
- * * "Avatar stack":/spaces/avatar
- * * "Member location":/spaces/locations
- * * "Live cursors":/spaces/cursors
- * * "Component locking":/spaces/locking
+ * - [Avatar stack](/spaces/avatar)
+ * - [Member location](/spaces/locations)
+ * - [Live cursors](/spaces/cursors)
+ * - [Component locking](/spaces/locking)
  *
- * 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.
+ * 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 [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.
  *
  * To subscribe to any events in a space, you first need to create or retrieve a space.
+ *
  * <!-- END WEBSITE DOCUMENTATION -->
  *
  * > **Documentation source**
@@ -176,17 +177,17 @@ class Space extends EventEmitter<SpaceEventMap> {
    * >
    * > The following documentation is copied from the [Spaces documentation website](https://ably.com/docs/spaces).
    * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/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 [`enter`](/spaces/members#events) event to all subscribers. Use the `enter()` method to enter a space.
    *
    * Being entered into a space is required for members to:
    *
-   * * Update their "profile data":#update-profile.
-   * * Set their "location":/spaces/locations.
-   * * Set their "cursor position":/spaces/cursors.
+   * - Update their [profile data](#update-profile).
+   * - Set their [location](/spaces/locations).
+   * - Set their [cursor position](/spaces/cursors).
    *
    * The following is an example of entering a space:
    *
-   * ```[javascript]
+   * ```javascript
    * await space.enter();
    * ```
    * <!-- END WEBSITE DOCUMENTATION -->
@@ -195,13 +196,13 @@ class Space extends EventEmitter<SpaceEventMap> {
    * >
    * > The following documentation is copied from the [Spaces documentation website](https://ably.com/docs/spaces).
    * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/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.
+   * 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.
    *
    * Profile data is returned in the payload of all space events.
    *
    * The following is an example of setting profile data when entering a space:
    *
-   * ```[javascript]
+   * ```javascript
    * await space.enter({
    *   username: 'Claire Oranges',
    *   avatar: 'https://slides-internal.com/users/coranges.png',
@@ -244,20 +245,19 @@ class Space extends EventEmitter<SpaceEventMap> {
 
   /**
    * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/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.
+   * 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.
    *
    * The following is an example of updating profile data:
    *
-   * ```[javascript]
+   * ```javascript
    * space.updateProfileData({
    *   username: 'Claire Lemons',
    *   avatar: 'https://slides-internal.com/users/clemons.png',
    * });
    * ```
+   * A function can be passed to `updateProfileData()` in order to update a field based on the existing profile data:
    *
-   * A function can be passed to @updateProfileData()@ in order to update a field based on the existing profile data:
-   *
-   * ```[javascript]
+   * ```javascript
    * space.updateProfileData(currentProfile => {
    *   return { ...currentProfile, username: 'Clara Lemons' }
    * });
@@ -312,15 +312,15 @@ class Space extends EventEmitter<SpaceEventMap> {
 
   /*
    * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/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 [`leave`](/spaces/members#events) event to all subscribers.
    *
    * The following is an example of explicitly leaving a space:
    *
-   * ```[javascript]
+   * ```javascript
    * await space.leave();
    * ```
+   * Members will implicitly leave a space after 15 seconds if they abruptly disconnect. If experiencing network disruption, and they reconnect within 15 seconds, then they will remain part of the space and no `leave` event will be emitted.
    *
-   * Members will implicitly leave a space after 15 seconds if they abruptly disconnect. If experiencing network disruption, and they reconnect within 15 seconds, then they will remain part of the space and no @leave@ event will be emitted.
    * <!-- END WEBSITE DOCUMENTATION -->
    *
    * > **Documentation source**
@@ -356,11 +356,11 @@ class Space extends EventEmitter<SpaceEventMap> {
 
   /**
    * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/content/spaces/space.textile?plain=1#L191-L197) -->
-   * The current state of the space can be retrieved in a one-off call. This will return an array of all @member@ objects currently in the space. This is a local call and retrieves the membership of the space retained in memory by the SDK.
+   * The current state of the space can be retrieved in a one-off call. This will return an array of all `member` objects currently in the space. This is a local call and retrieves the membership of the space retained in memory by the SDK.
    *
    * The following is an example of retrieving the current space state. Ths includes members that have recently left the space, but have not yet been removed:
    *
-   * ```[javascript]
+   * ```javascript
    * const spaceState = await space.getState();
    * ```
    * <!-- END WEBSITE DOCUMENTATION -->
@@ -372,34 +372,41 @@ class Space extends EventEmitter<SpaceEventMap> {
 
   /**
    * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/content/spaces/space.textile?plain=1#L107-L177) -->
-   * Subscribe to space state updates by registering a listener. Use the @subscribe()@ method on the @space@ object to receive updates.
+   * Subscribe to space state updates by registering a listener. Use the `subscribe()` method on the `space` object to receive updates.
    *
    * The following events will trigger a space event:
    *
-   * * A member enters the space
-   * * A member leaves the space
-   * * A member is removed from the space state "after the offlineTimeout period":#options has elapsed
-   * * A member updates their profile data
-   * * A member sets a new location
+   * - A member enters the space
+   * - A member leaves the space
+   * - A member is removed from the space state [after the offlineTimeout period](#options) has elapsed
+   * - A member updates their profile data
+   * - A member sets a new location
    *
-   * Space state contains a single object called @members@. Any events that trigger a change in space state will always return the current state of the space as an array of @member@ objects.
+   * Space state contains a single object called `members`. Any events that trigger a change in space state will always return the current state of the space as an array of `member` objects.
    *
    * <aside data-type='note'>
-   * <p>"Avatar stacks":/spaces/members and "member location":/spaces/locations events can be subscribed to on their individual namespaces; @space.members@ and @space.locations@. These events are filtered versions of space state events. Only a single "message":/channels/messages is published per event by Ably, irrespective of whether you register listeners for space state or individual namespaces. If you register listeners for both, it is still only a single message.</p>
-   * <p>The key difference between the subscribing to space state or to individual feature events, is that space state events return the current state of the space as an array of all members in each event payload. Individual member and location event payloads only include the relevant data for the member that triggered the event.</p>
+   * <p>
+   *
+   * [Avatar stacks](/spaces/members) and [member location](/spaces/locations) events can be subscribed to on their individual namespaces; `space.members` and `space.locations`. These events are filtered versions of space state events. Only a single [message](/channels/messages) is published per event by Ably, irrespective of whether you register listeners for space state or individual namespaces. If you register listeners for both, it is still only a single message.
+   *
+   * </p>
+   * <p>
+   *
+   * The key difference between the subscribing to space state or to individual feature events, is that space state events return the current state of the space as an array of all members in each event payload. Individual member and location event payloads only include the relevant data for the member that triggered the event.
+   *
+   * </p>
    * </aside>
    *
    * The following is an example of subscribing to space events:
    *
-   * ```[javascript]
+   * ```javascript
    * space.subscribe('update', (spaceState) => {
    *   console.log(spaceState.members);
    * });
    * ```
-   *
    * The following is an example payload of a space event.
    *
-   * ```[json]
+   * ```json
    * [
    *     {
    *         "clientId": "clemons#142",
@@ -432,17 +439,18 @@ class Space extends EventEmitter<SpaceEventMap> {
    *     ...
    * ]
    * ```
+   * The following are the properties of an individual `member` within a space event payload:
+   *
+   * | Property            | Description                                                            | Type    |
+   * |---------------------|------------------------------------------------------------------------|---------|
+   * | clientId            | The [client identifier](/auth/identified-clients) for the member.      | String  |
+   * | connectionId        | The unique identifier of the member’s [connection](/connect).          | String  |
+   * | isConnected         | Whether the member is connected to Ably or not.                        | Boolean |
+   * | profileData         | The optional [profile data](#profile-data) associated with the member. | Object  |
+   * | location            | The current [location](/spaces/locations) of the member.               | Object  |
+   * | lastEvent.name      | The most recent event emitted by the member.                           | String  |
+   * | lastEvent.timestamp | The timestamp of the most recently emitted event.                      | Number  |
    *
-   * The following are the properties of an individual @member@ within a space event payload:
-   *
-   * |_. Property |_. Description |_. Type |
-   * | clientId | The "client identifier":/auth/identified-clients for the member. | String |
-   * | connectionId | The unique identifier of the member's "connection":/connect. | String |
-   * | isConnected | Whether the member is connected to Ably or not. | Boolean |
-   * | profileData | The optional "profile data":#profile-data associated with the member. | Object |
-   * | location | The current "location":/spaces/locations of the member. | Object |
-   * | lastEvent.name | The most recent event emitted by the member. | String |
-   * | lastEvent.timestamp | The timestamp of the most recently emitted event. | Number |
    * <!-- END WEBSITE DOCUMENTATION -->
    */
   subscribe<K extends keyof SpaceEventMap>(eventOrEvents: K | K[], listener?: EventListener<SpaceEventMap, K>): void;
@@ -470,7 +478,7 @@ class Space extends EventEmitter<SpaceEventMap> {
    *
    * The following is an example of removing a listener:
    *
-   * ```[javascript]
+   * ```javascript
    * space.unsubscribe('update', listener);
    * ```
    * <!-- END WEBSITE DOCUMENTATION -->
diff --git a/src/Spaces.ts b/src/Spaces.ts
index 9e401858..1df3039c 100644
--- a/src/Spaces.ts
+++ b/src/Spaces.ts
@@ -94,18 +94,18 @@ class Spaces {
    * >
    * > The following documentation is copied from the [Spaces documentation website](https://ably.com/docs/spaces).
    * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/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.
+   * 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.
    *
    * The following restrictions apply to space names:
    *
-   * * Avoid starting names with @[@ or @:@
-   * * Ensure names aren't empty
-   * * Exclude whitespace and wildcards, such as @*@
-   * * Use the correct case, whether it be uppercase or lowercase
+   * - Avoid starting names with `[` or `:`
+   * - Ensure names aren’t empty
+   * - Exclude whitespace and wildcards, such as `*`
+   * - Use the correct case, whether it be uppercase or lowercase
    *
    * The following is an example of creating a space:
    *
-   * ```[javascript]
+   * ```javascript
    * const space = await spaces.get('board-presentation');
    * ```
    * <!-- END WEBSITE DOCUMENTATION -->
@@ -114,73 +114,76 @@ class Spaces {
    * >
    * > The following documentation is copied from the [Spaces documentation website](https://ably.com/docs/spaces).
    * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/content/spaces/space.textile?plain=1#L199-L242) -->
-   * h2(#advanced). Advanced properties
+   * ## Advanced properties
    *
-   * The following sections are only relevant if you want to further customize a space, or understand more about the Spaces SDK. They aren't required to get up and running with the basics.
+   * The following sections are only relevant if you want to further customize a space, or understand more about the Spaces SDK. They aren’t required to get up and running with the basics.
    *
-   * h3(#options). Space options
+   * ### Space options
    *
-   * An additional set of optional properties may be passed when "creating or retrieving":#create a space to customize the behavior of different features.
+   * An additional set of optional properties may be passed when [creating or retrieving](#create) a space to customize the behavior of different features.
    *
    * The following properties can be customized:
    *
-   * |_. 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.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 |
+   * | 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.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 |
    *
-   * The following is an example of customizing the space options when calling @spaces.get()@:
+   * The following is an example of customizing the space options when calling `spaces.get()`:
    *
-   * ```[javascript]
+   * ```javascript
    * const space = await spaces.get('board-presentation', {
    * 	offlineTimeout: 180_000,
    * 	cursors: { paginationLimit: 10 }
    * });
    * ```
+   * ### Space foundations
    *
-   * h3(#foundations). Space 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.
    *
-   * 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.
+   * A space is created as an Ably [channel](/channels). Members [attach](/channels#attach) to the channel and join its [presence set](/presence-occupancy/presence) when they [enter](#enter) the space. Avatar stacks, member locations and component locking are all handled on this channel.
    *
-   * A space is created as an Ably "channel":/channels. Members "attach":/channels#attach to the channel and join its "presence set":/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":/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](/channels#states). The channel object can be accessed through `space.channel`.
    *
    * The following is an example of registering a listener to wait for a channel to become attached:
    *
-   * ```[javascript]
+   * ```javascript
    * space.channel.on('attached', (stateChange) => {
    *   console.log(stateChange)
    * });
    * ```
-   *
    * <aside data-type='note'>
    * <p>
-   * Due to the high frequency at which updates are streamed for cursor movements, live cursors utilizes its own "channel":/channels.
+   *
+   * Due to the high frequency at which updates are streamed for cursor movements, live cursors utilizes its own [channel](/channels).
+   *
    * </p>
    * </aside>
+   *
    * <!-- END WEBSITE DOCUMENTATION -->
    *
    * > **Documentation source**
    * >
    * > The following documentation is copied from the [Spaces documentation website](https://ably.com/docs/spaces).
    * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/content/spaces/cursors.textile?plain=1#L108-L122) -->
-   * h2(#options). Cursor options
+   * ## Cursor options
    *
-   * Cursor options are set when creating or retrieving a @Space@ instance. They are used to control the behavior of live cursors.
+   * 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:
    *
-   * h3(#batch). outboundBatchInterval
+   * ### outboundBatchInterval
+   *
+   * The `outboundBatchInterval` is the interval at which a batch of cursor positions are published, in milliseconds, for each client. This is multiplied by the number of members in a space.
    *
-   * The @outboundBatchInterval@ is the interval at which a batch of cursor positions are published, in milliseconds, for each client. This is multiplied by the number of members in a space.
+   * The default value is 25ms which is optimal for the majority of use cases. If you wish to optimize the interval further, then decreasing the value will improve performance by further ‘smoothing’ the movement of cursors at the cost of increasing the number of events sent. Be aware that at a certain point the rate at which a browser is able to render the changes will impact optimizations.
    *
-   * The default value is 25ms which is optimal for the majority of use cases. If you wish to optimize the interval further, then decreasing the value will improve performance by further 'smoothing' the movement of cursors at the cost of increasing the number of events sent. Be aware that at a certain point the rate at which a browser is able to render the changes will impact optimizations.
+   * ### paginationLimit
    *
-   * h3(#pagination). paginationLimit
+   * The volume of messages sent can be high when using live cursors. Because of this, the last known position of every members’ cursor is obtained from [history](/storage-history/history). The `paginationLimit` is the number of pages that should be searched to find the last position of each cursor. The default is 5.
    *
-   * The volume of messages sent can be high when using live cursors. Because of this, the last known position of every members' cursor is obtained from "history":/storage-history/history. The @paginationLimit@ is the number of pages that should be searched to find the last position of each cursor. The default is 5.
    * <!-- END WEBSITE DOCUMENTATION -->
    *
    * > **Documentation source**

From 8a03caf21d106efa9119be80069a3940029eb0b1 Mon Sep 17 00:00:00 2001
From: Lawrence Forooghian <lawrence@forooghian.com>
Date: Tue, 26 Sep 2023 16:09:08 -0300
Subject: [PATCH 22/30] Remove scripts/convert_website_documentation.ts

This reverts bff065b; the script is no longer needed after we ran it in
60d482e.
---
 package.json                             |   4 +-
 scripts/convert_website_documentation.ts | 183 -----------------------
 2 files changed, 2 insertions(+), 185 deletions(-)
 delete mode 100644 scripts/convert_website_documentation.ts

diff --git a/package.json b/package.json
index 623737b3..b06ddb0a 100644
--- a/package.json
+++ b/package.json
@@ -9,8 +9,8 @@
   "scripts": {
     "lint": "eslint .",
     "lint:fix": "eslint --fix .",
-    "format": "prettier --write --ignore-path .gitignore src demo scripts",
-    "format:check": "prettier --check --ignore-path .gitignore src demo scripts",
+    "format": "prettier --write --ignore-path .gitignore src demo",
+    "format:check": "prettier --check --ignore-path .gitignore src demo",
     "test": "vitest run",
     "test:watch": "vitest watch",
     "coverage": "vitest run --coverage",
diff --git a/scripts/convert_website_documentation.ts b/scripts/convert_website_documentation.ts
deleted file mode 100644
index a79e4807..00000000
--- a/scripts/convert_website_documentation.ts
+++ /dev/null
@@ -1,183 +0,0 @@
-import { readdir, lstat, readFile, writeFile } from 'node:fs/promises';
-import { join } from 'node:path';
-import { execFile } from 'node:child_process';
-
-async function processDirectory(path: string) {
-  const entries = await readdir(path);
-
-  for (const entry of entries) {
-    const pathToEntry = join(path, entry);
-
-    const stat = await lstat(pathToEntry);
-    if (stat.isDirectory()) {
-      await processDirectory(pathToEntry);
-      continue;
-    }
-
-    if (entry.endsWith('.ts')) {
-      await processFile(pathToEntry);
-    }
-  }
-}
-
-async function processFile(path: string) {
-  console.log(`Processing: ${path}`);
-  const contents = await readFile(path, { encoding: 'utf-8' });
-
-  const beginWebsiteDocumentationRegexp = /<!-- BEGIN WEBSITE DOCUMENTATION \(.*\) -->/g;
-  const endWebsiteDocumentationRegexp = /<!-- END WEBSITE DOCUMENTATION -->/g;
-
-  const lines = contents.split('\n');
-
-  const startLineIndices: number[] = [];
-  const endLineIndices: number[] = [];
-
-  for (const [lineIndex, line] of lines.entries()) {
-    if (beginWebsiteDocumentationRegexp.exec(line)) {
-      startLineIndices.push(lineIndex);
-    }
-    if (endWebsiteDocumentationRegexp.exec(line)) {
-      endLineIndices.push(lineIndex);
-    }
-  }
-
-  for (let documentationIndex = 0; documentationIndex < startLineIndices.length; documentationIndex++) {
-    const startLineIndex = startLineIndices[documentationIndex];
-    const endLineIndex = endLineIndices[documentationIndex];
-
-    const documentation = lines.slice(startLineIndex + 1, endLineIndex).join('\n');
-    const documentationLineCount = endLineIndex - startLineIndex - 1;
-
-    // Convert the documentation comment.
-    const converted = await convertWebsiteDocumentationCommentFragment(documentation);
-
-    // Replace the documentation comment in `lines`.
-    const convertedLines = converted.split('\n');
-    lines.splice(startLineIndex + 1, documentationLineCount, ...convertedLines);
-
-    const addedLinesCount = convertedLines.length - documentationLineCount;
-
-    // Shift the line indices to reflect the length of the converted documentation comment.
-    for (
-      let indexOfDocumentationToShiftLineNumbers = documentationIndex + 1;
-      indexOfDocumentationToShiftLineNumbers < startLineIndices.length;
-      indexOfDocumentationToShiftLineNumbers++
-    ) {
-      startLineIndices[indexOfDocumentationToShiftLineNumbers] += addedLinesCount;
-      endLineIndices[indexOfDocumentationToShiftLineNumbers] += addedLinesCount;
-    }
-  }
-
-  // Write the new contents of the file.
-  const newContents = lines.join('\n');
-  await writeFile(path, newContents, { encoding: 'utf-8' });
-}
-
-async function convertWebsiteDocumentationCommentFragment(commentFragment: string) {
-  const prefixStrippingResult = strippingPrefixOfCommentFragment(commentFragment);
-  const tagged = tagCommentFragmentLines(prefixStrippingResult.content);
-
-  const lines: string[] = [];
-
-  for (const taggedLines of tagged) {
-    switch (taggedLines.type) {
-      case 'textile':
-        lines.push(...(await convertTextileLines(taggedLines.lines)));
-        break;
-      case 'codeBlock':
-        lines.push(...convertCodeBlockLines(taggedLines.lines));
-        break;
-    }
-  }
-
-  return restoringPrefixOfCommentFragment(lines.join('\n'), prefixStrippingResult.prefix);
-}
-
-async function convertTextileLines(textileLines: string[]) {
-  const pandocStdoutPromise = new Promise<string>((resolve, reject) => {
-    const childProcess = execFile(
-      '/opt/homebrew/bin/pandoc',
-      // We choose gfm over commonmark for tables support.
-      ['--from', 'textile', '--to', 'gfm', '--wrap=preserve'],
-      (error, stdout, stderr) => {
-        if (error) {
-          reject(error);
-        } else {
-          resolve(stdout);
-        }
-      },
-    );
-
-    // I don’t fully understand how writing works and whether this always succeeds in writing the full thing; keep an eye out for any weirdness and revisit if necessary.
-    childProcess.stdin!.write(textileLines.join('\n'));
-    childProcess.stdin!.end();
-  });
-
-  const pandocStdout = await pandocStdoutPromise;
-
-  return pandocStdout.split('\n');
-}
-
-function convertCodeBlockLines(codeBlockLines: string[]) {
-  // remove square brackets from language tag
-  const firstLine = codeBlockLines[0].replace(/[[\]]/g, '');
-  return [firstLine, ...codeBlockLines.slice(1)];
-}
-
-type TaggedLines = { type: 'textile' | 'codeBlock'; lines: string[] };
-
-function tagCommentFragmentLines(commentFragment: string) {
-  const lines = commentFragment.split('\n');
-
-  const result: TaggedLines[] = [];
-
-  let current: TaggedLines | null = null;
-
-  for (const line of lines) {
-    if (line.startsWith('```')) {
-      if (current && current.type === 'codeBlock') {
-        // end of code block
-        current.lines.push(line);
-        result.push(current);
-        current = null;
-      } else {
-        if (current) {
-          result.push(current);
-        }
-
-        // start of code block
-        current = { type: 'codeBlock', lines: [line] };
-      }
-    } else {
-      if (current) {
-        current.lines.push(line);
-      } else {
-        current = { type: 'textile', lines: [line] };
-      }
-    }
-  }
-
-  if (current) {
-    result.push(current);
-    current = null;
-  }
-
-  return result;
-}
-
-function strippingPrefixOfCommentFragment(commentFragment: string) {
-  const lines = commentFragment.split('\n');
-  const prefix = /\s+\* /g.exec(lines[0])![0];
-  const newLines = lines.map((line) => line.substring(prefix.length));
-
-  return { content: newLines.join('\n'), prefix };
-}
-
-function restoringPrefixOfCommentFragment(content: string, prefix: string) {
-  const lines = content.split('\n');
-  const newLines = lines.map((line) => `${prefix}${line}`);
-
-  return newLines.join('\n');
-}
-
-processDirectory('src');

From 2cf88baa4893fb1b6f291c992337cbc2beeaf60a Mon Sep 17 00:00:00 2001
From: Lawrence Forooghian <lawrence@forooghian.com>
Date: Thu, 21 Sep 2023 17:14:55 -0300
Subject: [PATCH 23/30] Convert <aside> elements into quotes with strong text
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The docs repo has a bunch of CSS for making these stand out visually,
but we don’t have any of that when using TypeDoc (I guess I could
configure it but don’t really want to put time into it now), so instead
just use the tools at our disposal to make these sections stand out
visually.
---
 src/Cursors.ts   | 58 +++++++++++++-----------------------------------
 src/Locations.ts | 20 +++++------------
 src/Locks.ts     | 20 +++++------------
 src/Members.ts   | 20 +++++------------
 src/Space.ts     | 17 +++++---------
 src/Spaces.ts    |  9 +++-----
 6 files changed, 41 insertions(+), 103 deletions(-)

diff --git a/src/Cursors.ts b/src/Cursors.ts
index f06e3702..eef64587 100644
--- a/src/Cursors.ts
+++ b/src/Cursors.ts
@@ -28,13 +28,9 @@ const CURSORS_CHANNEL_TAG = '::$cursors';
  *
  * Live cursor updates are not available as part of the [space state](/spaces/space#subscribe) and must be subscribed to using [`space.cursors.subscribe()`](#subscribe).
  *
- * <aside data-type='important'>
- * <p>
- *
- * Live cursors are a great way of providing contextual awareness as to what members are looking at within an application. However, too many cursors moving across a page can often be a distraction rather than an enhancement. As such, Ably recommends a maximum of 20 members simultaneously streaming their cursors in a space at any one time for an optimal end-user experience.
- *
- * </p>
- * </aside>
+ * > **Important**
+ * >
+ * > Live cursors are a great way of providing contextual awareness as to what members are looking at within an application. However, too many cursors moving across a page can often be a distraction rather than an enhancement. As such, Ably recommends a maximum of 20 members simultaneously streaming their cursors in a space at any one time for an optimal end-user experience.
  *
  * <!-- END WEBSITE DOCUMENTATION -->
  *
@@ -106,35 +102,15 @@ export default class Cursors extends EventEmitter<CursorsEventMap> {
    * | 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, such as a color. | Object |
    *
-   * <aside data-type='note'>
-   * <p>
-   *
-   * The `data` parameter can be used to stream additional information related to a cursor’s movement, such as:
-   *
-   * </p>
-   * <ul>
-   * <li>
-   *
-   * The color that other member’s should display a cursor as.
-   *
-   * </li>
-   * <li>
-   *
-   * The ID of an element that a user may be dragging for drag and drop functionality.
-   *
-   * </li>
-   * <li>
-   *
-   * Details of any cursor annotations.
-   *
-   * </li>
-   * </ul>
-   * <p>
-   *
-   * Be aware that as live cursor updates are batched it is not advisable to publish data unrelated to cursor position in the `data` parameter. Use a [pub/sub channel](/channels) instead.
-   *
-   * </p>
-   * </aside>
+   * > **Note**
+   * >
+   * > The `data` parameter can be used to stream additional information related to a cursor’s movement, such as:
+   * >
+   * > - The color that other member’s should display a cursor as.
+   * > - The ID of an element that a user may be dragging for drag and drop functionality.
+   * > - Details of any cursor annotations.
+   * >
+   * > Be aware that as live cursor updates are batched it is not advisable to publish data unrelated to cursor position in the `data` parameter. Use a [pub/sub channel](/channels) instead.
    *
    * The following is an example of a member setting their cursor position by adding an event listener to obtain their cursor coordinates and then publishing their position using the `set()` method:
    *
@@ -255,13 +231,9 @@ export default class Cursors extends EventEmitter<CursorsEventMap> {
    * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/content/spaces/cursors.textile?plain=1#L78-L90) -->
    * Subscribe to cursor events by registering a listener. Cursor events are emitted whenever a member moves their cursor by calling `set()`. Use the `subscribe()` method on the `cursors` object of a space to receive updates.
    *
-   * <aside data-type='note'>
-   * <p>
-   *
-   * The rate at which cursor events are published is controlled by the `outboundBatchInterval` property set in the [cursor options](#options) of a space.
-   *
-   * </p>
-   * </aside>
+   * > **Note**
+   * >
+   * > The rate at which cursor events are published is controlled by the `outboundBatchInterval` property set in the [cursor options](#options) of a space.
    *
    * The following is an example of subscribing to cursor events:
    *
diff --git a/src/Locations.ts b/src/Locations.ts
index d5401cb8..0aabf48b 100644
--- a/src/Locations.ts
+++ b/src/Locations.ts
@@ -134,13 +134,9 @@ export default class Locations extends EventEmitter<LocationsEventMap> {
    *
    * 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`.
    *
-   * <aside data-type='note'>
-   * <p>
-   *
-   * 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.
-   *
-   * </p>
-   * </aside>
+   * > **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.
    *
    * The following is an example of subscribing to location events:
    *
@@ -193,13 +189,9 @@ export default class Locations extends EventEmitter<LocationsEventMap> {
    * | previousLocation           | The previous location of the member.                                                                                  | Object  |
    * | currentLocation            | The new location of the member.                                                                                       | Object  |
    *
-   * <aside data-type='further-reading'>
-   * <p>
-   *
-   * 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, [space state](/spaces/space) can be subscribed to which returns an array of all members with their latest state every time any event is triggered.
-   *
-   * </p>
-   * </aside>
+   * > **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, [space state](/spaces/space) can be subscribed to which returns an array of all members with their latest state every time any event is triggered.
    *
    * <!-- END WEBSITE DOCUMENTATION -->
    *
diff --git a/src/Locks.ts b/src/Locks.ts
index 60672271..624d68da 100644
--- a/src/Locks.ts
+++ b/src/Locks.ts
@@ -45,13 +45,9 @@ export interface LocksEventMap {
  *
  * Each lock is identified by a unique string ID, and only a single member may hold a lock with a given string at any one time. A lock will exist in one of three [states](#states) and may only transition between states in specific circumstances.
  *
- * <aside data-type='important'>
- * <p>
- *
- * Optimistic locking means that there is a chance that two members may begin editing the same UI component before it is confirmed which member holds the lock. On average, the time taken to reconcile which member holds a lock is in the hundreds of milliseconds. Your application needs to handle the member that successfully obtained the lock, as well as the member that had their request invalidated.
- *
- * </p>
- * </aside>
+ * > **Important**
+ * >
+ * > Optimistic locking means that there is a chance that two members may begin editing the same UI component before it is confirmed which member holds the lock. On average, the time taken to reconcile which member holds a lock is in the hundreds of milliseconds. Your application needs to handle the member that successfully obtained the lock, as well as the member that had their request invalidated.
  *
  * ## Lock states
  *
@@ -411,13 +407,9 @@ export default class Locks extends EventEmitter<LocksEventMap> {
    * ```
    * Releasing a lock will emit a lock event with a [lock status](#states) of `unlocked`.
    *
-   * <aside data-type='note'>
-   * <p>
-   *
-   * When a member [leaves](/spaces/space#leave) a space, their locks are automatically released.
-   *
-   * </p>
-   * </aside>
+   * > **Note**
+   * >
+   * > When a member [leaves](/spaces/space#leave) a space, their locks are automatically released.
    *
    * <!-- END WEBSITE DOCUMENTATION -->
    *
diff --git a/src/Members.ts b/src/Members.ts
index b6b2c754..a1913c81 100644
--- a/src/Members.ts
+++ b/src/Members.ts
@@ -38,13 +38,9 @@ export interface MembersEventMap {
  * `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.
  *
- * <aside data-type='note'>
- * <p>
- *
- * Members [enter](/spaces/space#enter), [leave](/spaces/space#leave), and [update](/spaces/space#update-profile) a [space](/spaces/space) directly. The `members` namespace is used to subscribe to these updates.
- *
- * </p>
- * </aside>
+ * > **Note**
+ * >
+ * > Members [enter](/spaces/space#enter), [leave](/spaces/space#leave), and [update](/spaces/space#update-profile) a [space](/spaces/space) directly. The `members` namespace is used to subscribe to these updates.
  *
  * <!-- END WEBSITE DOCUMENTATION -->
  *
@@ -377,13 +373,9 @@ class Members extends EventEmitter<MembersEventMap> {
    * | lastEvent.name      | The most recent event emitted by the member.                                                                      | String  |
    * | lastEvent.timestamp | The timestamp of the most recently emitted event.                                                                 | Number  |
    *
-   * <aside data-type='further-reading'>
-   * <p>
-   *
-   * Avatar stack subscription listeners only trigger on events related to members’ online status and profile updates. Each event only contains the payload of the member that triggered it. Alternatively, [space state](/spaces/space) can be subscribed to which returns an array of all members with their latest state every time any event is triggered.
-   *
-   * </p>
-   * </aside>
+   * > **Further reading**
+   * >
+   * > Avatar stack subscription listeners only trigger on events related to members’ online status and profile updates. Each event only contains the payload of the member that triggered it. Alternatively, [space state](/spaces/space) can be subscribed to which returns an array of all members with their latest state every time any event is triggered.
    *
    * <!-- END WEBSITE DOCUMENTATION -->
    *
diff --git a/src/Space.ts b/src/Space.ts
index d9d63ebb..deb73c1c 100644
--- a/src/Space.ts
+++ b/src/Space.ts
@@ -384,18 +384,11 @@ class Space extends EventEmitter<SpaceEventMap> {
    *
    * Space state contains a single object called `members`. Any events that trigger a change in space state will always return the current state of the space as an array of `member` objects.
    *
-   * <aside data-type='note'>
-   * <p>
-   *
-   * [Avatar stacks](/spaces/members) and [member location](/spaces/locations) events can be subscribed to on their individual namespaces; `space.members` and `space.locations`. These events are filtered versions of space state events. Only a single [message](/channels/messages) is published per event by Ably, irrespective of whether you register listeners for space state or individual namespaces. If you register listeners for both, it is still only a single message.
-   *
-   * </p>
-   * <p>
-   *
-   * The key difference between the subscribing to space state or to individual feature events, is that space state events return the current state of the space as an array of all members in each event payload. Individual member and location event payloads only include the relevant data for the member that triggered the event.
-   *
-   * </p>
-   * </aside>
+   * > **Note**
+   * >
+   * > [Avatar stacks](/spaces/members) and [member location](/spaces/locations) events can be subscribed to on their individual namespaces; `space.members` and `space.locations`. These events are filtered versions of space state events. Only a single [message](/channels/messages) is published per event by Ably, irrespective of whether you register listeners for space state or individual namespaces. If you register listeners for both, it is still only a single message.
+   * >
+   * > The key difference between the subscribing to space state or to individual feature events, is that space state events return the current state of the space as an array of all members in each event payload. Individual member and location event payloads only include the relevant data for the member that triggered the event.
    *
    * The following is an example of subscribing to space events:
    *
diff --git a/src/Spaces.ts b/src/Spaces.ts
index 1df3039c..dad8a6b2 100644
--- a/src/Spaces.ts
+++ b/src/Spaces.ts
@@ -154,13 +154,10 @@ class Spaces {
    *   console.log(stateChange)
    * });
    * ```
-   * <aside data-type='note'>
-   * <p>
    *
-   * Due to the high frequency at which updates are streamed for cursor movements, live cursors utilizes its own [channel](/channels).
-   *
-   * </p>
-   * </aside>
+   * > **Note**
+   * >
+   * > Due to the high frequency at which updates are streamed for cursor movements, live cursors utilizes its own [channel](/channels).
    *
    * <!-- END WEBSITE DOCUMENTATION -->
    *

From ffdd226823b81bec9dbc220e6f66bb1a200d1e3e Mon Sep 17 00:00:00 2001
From: Lawrence Forooghian <lawrence@forooghian.com>
Date: Thu, 21 Sep 2023 13:23:03 -0300
Subject: [PATCH 24/30] Make links to external documentation absolute

The relative links were designed for content contained within the
ably.com/docs site, which the HTML documentation we generate with
TypeDoc will not necessarily be.
---
 src/Cursors.ts   | 12 ++++++------
 src/Locations.ts |  6 +++---
 src/Locks.ts     |  4 ++--
 src/Members.ts   |  6 +++---
 src/Space.ts     |  6 +++---
 src/Spaces.ts    |  8 ++++----
 6 files changed, 21 insertions(+), 21 deletions(-)

diff --git a/src/Cursors.ts b/src/Cursors.ts
index eef64587..8fb09d4e 100644
--- a/src/Cursors.ts
+++ b/src/Cursors.ts
@@ -42,11 +42,11 @@ const CURSORS_CHANNEL_TAG = '::$cursors';
  *
  * 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.
  *
- * Live cursors build upon the functionality of the Pub/Sub Channels [presence](/presence-occupancy/presence) feature.
+ * Live cursors build upon the functionality of the Pub/Sub Channels [presence](https://ably.com/docs/presence-occupancy/presence) feature.
  *
- * Due to the high frequency at which updates are streamed for cursor movements, live cursors utilizes its own [channel](/channels). The other features of the Spaces SDK, such as avatar stacks, member locations and component locking all share a single channel. For this same reason, cursor position updates are not included in the [space state](/spaces/space) and may only be subscribed to on the `cursors` namespace.
+ * Due to the high frequency at which updates are streamed for cursor movements, live cursors utilizes its own [channel](https://ably.com/docs/channels). The other features of the Spaces SDK, such as avatar stacks, member locations and component locking all share a single channel. For this same reason, cursor position updates are not included in the [space state](/spaces/space) and may only be subscribed to on the `cursors` namespace.
  *
- * The channel is only created when a member calls `space.cursors.set()`. The live cursors channel object can be accessed through `space.cursors.channel`. To monitor the [underlying state of the cursors channel](/channels#states), the channel object can be accessed through `space.cursors.channel`.
+ * The channel is only created when a member calls `space.cursors.set()`. The live cursors channel object can be accessed through `space.cursors.channel`. To monitor the [underlying state of the cursors channel](https://ably.com/docs/channels#states), the channel object can be accessed through `space.cursors.channel`.
  *
  * <!-- END WEBSITE DOCUMENTATION -->
  *
@@ -110,7 +110,7 @@ export default class Cursors extends EventEmitter<CursorsEventMap> {
    * > - The ID of an element that a user may be dragging for drag and drop functionality.
    * > - Details of any cursor annotations.
    * >
-   * > Be aware that as live cursor updates are batched it is not advisable to publish data unrelated to cursor position in the `data` parameter. Use a [pub/sub channel](/channels) instead.
+   * > Be aware that as live cursor updates are batched it is not advisable to publish data unrelated to cursor position in the `data` parameter. Use a [pub/sub channel](https://ably.com/docs/channels) instead.
    *
    * The following is an example of a member setting their cursor position by adding an event listener to obtain their cursor coordinates and then publishing their position using the `set()` method:
    *
@@ -140,8 +140,8 @@ export default class Cursors extends EventEmitter<CursorsEventMap> {
    *
    * | Property     | Description                                                                                        | Type   |
    * |--------------|----------------------------------------------------------------------------------------------------|--------|
-   * | connectionId | The unique identifier of the member’s [connection](/connect).                                      | String |
-   * | clientId     | The [client identifier](/auth/identified-clients) for the member.                                  | String |
+   * | 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 |
diff --git a/src/Locations.ts b/src/Locations.ts
index 0aabf48b..40625067 100644
--- a/src/Locations.ts
+++ b/src/Locations.ts
@@ -37,7 +37,7 @@ export interface LocationsEventMap {
  *
  * 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](/presence-occupancy/presence) feature. Members are entered into the presence set when they [enter the space](/spaces/space#enter).
+ * 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 [enter the space](/spaces/space#enter).
  *
  * <!-- END WEBSITE DOCUMENTATION -->
  *
@@ -180,8 +180,8 @@ export default class Locations extends EventEmitter<LocationsEventMap> {
    *
    * | Property                   | Description                                                                                                           | Type    |
    * |----------------------------|-----------------------------------------------------------------------------------------------------------------------|---------|
-   * | member.clientId            | The [client identifier](/auth/identified-clients) for the member.                                                     | String  |
-   * | member.connectionId        | The unique identifier of the member’s [connection](/connect).                                                         | String  |
+   * | 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 `enter`, `update`, `leave` or `remove`. | String  |
    * | member.lastEvent.timestamp | The timestamp of the most recently emitted event.                                                                     | Number  |
diff --git a/src/Locks.ts b/src/Locks.ts
index 624d68da..9079d2d0 100644
--- a/src/Locks.ts
+++ b/src/Locks.ts
@@ -507,8 +507,8 @@ export default class Locks extends EventEmitter<LocksEventMap> {
    * | 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](/auth/identified-clients) for the member.                                                            | String    |
-   * | member.connectionId        | The unique identifier of the member’s [connection](/connect).                                                                | String    |
+   * | 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    |
diff --git a/src/Members.ts b/src/Members.ts
index a1913c81..091249aa 100644
--- a/src/Members.ts
+++ b/src/Members.ts
@@ -52,7 +52,7 @@ export interface MembersEventMap {
  *
  * 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.
  *
- * Avatar stacks build upon the functionality of the Pub/Sub Channels [presence](/presence-occupancy/presence) feature. Members are entered into the presence set when they [enter the space](/spaces/space#enter).
+ * Avatar stacks 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 [enter the space](/spaces/space#enter).
  *
  * <!-- END WEBSITE DOCUMENTATION -->
  *
@@ -365,8 +365,8 @@ class Members extends EventEmitter<MembersEventMap> {
    *
    * | Property            | Description                                                                                                       | Type    |
    * |---------------------|-------------------------------------------------------------------------------------------------------------------|---------|
-   * | clientId            | The [client identifier](/auth/identified-clients) for the member.                                                 | String  |
-   * | connectionId        | The unique identifier of the member’s [connection](/connect).                                                     | String  |
+   * | clientId            | The [client identifier](https://ably.com/docs/auth/identified-clients) for the member.                                                 | String  |
+   * | connectionId        | The unique identifier of the member’s [connection](https://ably.com/docs/connect).                                                     | String  |
    * | isConnected         | Whether the member is connected to Ably or not.                                                                   | Boolean |
    * | profileData         | The optional [profile data](#profile-data) associated with the member.                                            | Object  |
    * | location            | The current [location](/spaces/locations) of the member. Will be `null` for `enter`, `leave` and `remove` events. | Object  |
diff --git a/src/Space.ts b/src/Space.ts
index deb73c1c..b5f80656 100644
--- a/src/Space.ts
+++ b/src/Space.ts
@@ -386,7 +386,7 @@ class Space extends EventEmitter<SpaceEventMap> {
    *
    * > **Note**
    * >
-   * > [Avatar stacks](/spaces/members) and [member location](/spaces/locations) events can be subscribed to on their individual namespaces; `space.members` and `space.locations`. These events are filtered versions of space state events. Only a single [message](/channels/messages) is published per event by Ably, irrespective of whether you register listeners for space state or individual namespaces. If you register listeners for both, it is still only a single message.
+   * > [Avatar stacks](/spaces/members) and [member location](/spaces/locations) events can be subscribed to on their individual namespaces; `space.members` and `space.locations`. These events are filtered versions of space state events. Only a single [message](https://ably.com/docs/channels/messages) is published per event by Ably, irrespective of whether you register listeners for space state or individual namespaces. If you register listeners for both, it is still only a single message.
    * >
    * > The key difference between the subscribing to space state or to individual feature events, is that space state events return the current state of the space as an array of all members in each event payload. Individual member and location event payloads only include the relevant data for the member that triggered the event.
    *
@@ -436,8 +436,8 @@ class Space extends EventEmitter<SpaceEventMap> {
    *
    * | Property            | Description                                                            | Type    |
    * |---------------------|------------------------------------------------------------------------|---------|
-   * | clientId            | The [client identifier](/auth/identified-clients) for the member.      | String  |
-   * | connectionId        | The unique identifier of the member’s [connection](/connect).          | String  |
+   * | clientId            | The [client identifier](https://ably.com/docs/auth/identified-clients) for the member.      | String  |
+   * | connectionId        | The unique identifier of the member’s [connection](https://ably.com/docs/connect).          | String  |
    * | isConnected         | Whether the member is connected to Ably or not.                        | Boolean |
    * | profileData         | The optional [profile data](#profile-data) associated with the member. | Object  |
    * | location            | The current [location](/spaces/locations) of the member.               | Object  |
diff --git a/src/Spaces.ts b/src/Spaces.ts
index dad8a6b2..cfe938aa 100644
--- a/src/Spaces.ts
+++ b/src/Spaces.ts
@@ -143,9 +143,9 @@ class Spaces {
    *
    * 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.
    *
-   * A space is created as an Ably [channel](/channels). Members [attach](/channels#attach) to the channel and join its [presence set](/presence-occupancy/presence) when they [enter](#enter) the space. Avatar stacks, member locations and component locking are all handled on this channel.
+   * A space is created as an Ably [channel](/channels). Members [attach](https://ably.com/docs/channels#attach) to the channel and join its [presence set](https://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](/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](https://ably.com/docs/channels#states). The channel object can be accessed through `space.channel`.
    *
    * The following is an example of registering a listener to wait for a channel to become attached:
    *
@@ -157,7 +157,7 @@ class Spaces {
    *
    * > **Note**
    * >
-   * > Due to the high frequency at which updates are streamed for cursor movements, live cursors utilizes its own [channel](/channels).
+   * > Due to the high frequency at which updates are streamed for cursor movements, live cursors utilizes its own [channel](https://ably.com/docs/channels).
    *
    * <!-- END WEBSITE DOCUMENTATION -->
    *
@@ -179,7 +179,7 @@ class Spaces {
    *
    * ### paginationLimit
    *
-   * The volume of messages sent can be high when using live cursors. Because of this, the last known position of every members’ cursor is obtained from [history](/storage-history/history). The `paginationLimit` is the number of pages that should be searched to find the last position of each cursor. The default is 5.
+   * The volume of messages sent can be high when using live cursors. Because of this, the last known position of every members’ cursor is obtained from [history](https://ably.com/docs/storage-history/history). The `paginationLimit` is the number of pages that should be searched to find the last position of each cursor. The default is 5.
    *
    * <!-- END WEBSITE DOCUMENTATION -->
    *

From d14f7f9b3c12ad6e783e847a9617e70f43af29b4 Mon Sep 17 00:00:00 2001
From: Lawrence Forooghian <lawrence@forooghian.com>
Date: Thu, 21 Sep 2023 14:18:00 -0300
Subject: [PATCH 25/30] (WIP) Turn some stuff into @link

---
 src/Locations.ts | 17 +++++++++--------
 src/Space.ts     | 18 ++++++++++--------
 src/Spaces.ts    | 15 ++++++++-------
 3 files changed, 27 insertions(+), 23 deletions(-)

diff --git a/src/Locations.ts b/src/Locations.ts
index 40625067..eb1bad3c 100644
--- a/src/Locations.ts
+++ b/src/Locations.ts
@@ -45,7 +45,7 @@ export interface LocationsEventMap {
  * >
  * > The following documentation is copied from `docs/class-definitions.md`.
  * <!-- 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> {
@@ -107,6 +107,7 @@ export default class Locations extends EventEmitter<LocationsEventMap> {
    * >
    * > The following documentation is copied from `docs/class-definitions.md`.
    * <!-- 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
@@ -130,13 +131,13 @@ export default class Locations extends EventEmitter<LocationsEventMap> {
    * >
    * > The following documentation is copied from the [Spaces documentation website](https://ably.com/docs/spaces).
    * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/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:
    *
@@ -145,7 +146,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
    * {
@@ -183,7 +184,7 @@ export default class Locations extends EventEmitter<LocationsEventMap> {
    * | 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 `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  |
@@ -199,7 +200,7 @@ export default class Locations extends EventEmitter<LocationsEventMap> {
    * >
    * > The following documentation is copied from `docs/class-definitions.md`.
    * <!-- 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:
    *
@@ -257,7 +258,7 @@ export default class Locations extends EventEmitter<LocationsEventMap> {
    * >
    * > The following documentation is copied from `docs/class-definitions.md`.
    * <!-- 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');
diff --git a/src/Space.ts b/src/Space.ts
index b5f80656..71d6001c 100644
--- a/src/Space.ts
+++ b/src/Space.ts
@@ -50,7 +50,7 @@ export interface SpaceEventMap {
  *
  * 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.
  *
@@ -60,7 +60,7 @@ export interface SpaceEventMap {
  * >
  * > The following documentation is copied from `docs/class-definitions.md`.
  * <!-- 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 default.get | spaces.get}. Inherits from {@link EventEmitter}.
  * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
  */
 class Space extends EventEmitter<SpaceEventMap> {
@@ -72,7 +72,7 @@ class Space extends EventEmitter<SpaceEventMap> {
    * >
    * > The following documentation is copied from `docs/class-definitions.md`.
    * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
-   * An instance of [Locations](#locations).
+   * An instance of {@link Locations}.
    *
    * ```ts
    * type locations = instanceof Locations;
@@ -85,7 +85,7 @@ class Space extends EventEmitter<SpaceEventMap> {
    * >
    * > The following documentation is copied from `docs/class-definitions.md`.
    * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
-   * An instance of [Cursors](#cursors).
+   * An instance of {@link Cursors}.
    *
    * ```ts
    * type cursors = instanceof Cursors;
@@ -98,7 +98,7 @@ class Space extends EventEmitter<SpaceEventMap> {
    * >
    * > The following documentation is copied from `docs/class-definitions.md`.
    * <!-- BEGIN CLASS-DEFINITIONS DOCUMENTATION -->
-   * An instance of [Members](#members).
+   * An instance of {@link Members}.
    *
    * ```ts
    * type members = instanceof Members;
@@ -177,7 +177,7 @@ class Space extends EventEmitter<SpaceEventMap> {
    * >
    * > The following documentation is copied from the [Spaces documentation website](https://ably.com/docs/spaces).
    * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/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:
    *
@@ -214,6 +214,7 @@ class Space extends EventEmitter<SpaceEventMap> {
    * >
    * > The following documentation is copied from `docs/class-definitions.md`.
    * <!-- 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
@@ -245,7 +246,8 @@ class Space extends EventEmitter<SpaceEventMap> {
 
   /**
    * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/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:
    *
@@ -312,7 +314,7 @@ class Space extends EventEmitter<SpaceEventMap> {
 
   /*
    * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/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:
    *
diff --git a/src/Spaces.ts b/src/Spaces.ts
index cfe938aa..83ff6356 100644
--- a/src/Spaces.ts
+++ b/src/Spaces.ts
@@ -19,7 +19,7 @@ class Spaces {
    * >
    * > The following documentation is copied from `docs/class-definitions.md`.
    * <!-- 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;
@@ -32,7 +32,7 @@ class Spaces {
    * >
    * > The following documentation is copied from `docs/class-definitions.md`.
    * <!-- 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;
@@ -94,7 +94,8 @@ class Spaces {
    * >
    * > The following documentation is copied from the [Spaces documentation website](https://ably.com/docs/spaces).
    * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/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:
    *
@@ -127,7 +128,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 |
    *
@@ -145,7 +146,7 @@ class Spaces {
    *
    * A space is created as an Ably [channel](/channels). Members [attach](https://ably.com/docs/channels#attach) to the channel and join its [presence set](https://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](https://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](https://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:
    *
@@ -167,7 +168,7 @@ class Spaces {
    * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/content/spaces/cursors.textile?plain=1#L108-L122) -->
    * ## Cursor options
    *
-   * Cursor options are set when creating or retrieving a `Space` instance. They are used to control the behavior of live cursors.
+   * Cursor options are set when creating or retrieving a {@link Space | `Space` } instance. They are used to control the behavior of live cursors.
    *
    * The following cursor options can be set:
    *
@@ -187,7 +188,7 @@ class Spaces {
    * >
    * > The following documentation is copied from `docs/class-definitions.md`.
    * <!-- 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>;

From d057368099b33dddc1110d3689fe9e36b2f4328d Mon Sep 17 00:00:00 2001
From: Lawrence Forooghian <lawrence@forooghian.com>
Date: Thu, 21 Sep 2023 16:05:38 -0300
Subject: [PATCH 26/30] (WIP) Tweak references to "namespace"

---
 src/Cursors.ts   | 2 +-
 src/Locations.ts | 2 +-
 src/Locks.ts     | 2 +-
 src/Members.ts   | 4 ++--
 src/Space.ts     | 6 +++---
 5 files changed, 8 insertions(+), 8 deletions(-)

diff --git a/src/Cursors.ts b/src/Cursors.ts
index 8fb09d4e..02df595c 100644
--- a/src/Cursors.ts
+++ b/src/Cursors.ts
@@ -44,7 +44,7 @@ const CURSORS_CHANNEL_TAG = '::$cursors';
  *
  * Live cursors build upon the functionality of the Pub/Sub Channels [presence](https://ably.com/docs/presence-occupancy/presence) feature.
  *
- * Due to the high frequency at which updates are streamed for cursor movements, live cursors utilizes its own [channel](https://ably.com/docs/channels). The other features of the Spaces SDK, such as avatar stacks, member locations and component locking all share a single channel. For this same reason, cursor position updates are not included in the [space state](/spaces/space) and may only be subscribed to on the `cursors` namespace.
+ * Due to the high frequency at which updates are streamed for cursor movements, live cursors utilizes its own [channel](https://ably.com/docs/channels). The other features of the Spaces SDK, such as avatar stacks, member locations and component locking all share a single channel. For this same reason, cursor position updates are not included in the [space state](/spaces/space) and may only be subscribed to via the {@link Space.cursors | `cursors` } property.
  *
  * The channel is only created when a member calls `space.cursors.set()`. The live cursors channel object can be accessed through `space.cursors.channel`. To monitor the [underlying state of the cursors channel](https://ably.com/docs/channels#states), the channel object can be accessed through `space.cursors.channel`.
  *
diff --git a/src/Locations.ts b/src/Locations.ts
index eb1bad3c..82442138 100644
--- a/src/Locations.ts
+++ b/src/Locations.ts
@@ -131,7 +131,7 @@ export default class Locations extends EventEmitter<LocationsEventMap> {
    * >
    * > The following documentation is copied from the [Spaces documentation website](https://ably.com/docs/spaces).
    * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/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}. 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}.
    *
    * 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`}.
    *
diff --git a/src/Locks.ts b/src/Locks.ts
index 9079d2d0..ddcc4ea1 100644
--- a/src/Locks.ts
+++ b/src/Locks.ts
@@ -454,7 +454,7 @@ export default class Locks extends EventEmitter<LocksEventMap> {
    * >
    * > The following documentation is copied from the [Spaces documentation website](https://ably.com/docs/spaces).
    * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/content/spaces/locking.textile?plain=1#L92-L151) -->
-   * Subscribe to lock events by registering a listener. Lock events are emitted whenever the [lock state](#states) transitions into `locked` or `unlocked`. Use the `subscribe()` method on the `locks` namespace of the space to receive updates.
+   * Subscribe to lock events by registering a listener. Lock events are emitted whenever the [lock state](#states) transitions into `locked` or `unlocked`.
    *
    * All lock events are `update` events. When a lock event is received, UI components can be updated to add and remove visual indications of which member is locking them, as well as enabling and disabling the ability for other members to edit them.
    *
diff --git a/src/Members.ts b/src/Members.ts
index 091249aa..a5256383 100644
--- a/src/Members.ts
+++ b/src/Members.ts
@@ -20,7 +20,7 @@ export interface MembersEventMap {
  * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/14acea6dee7bf3872a3d32d43732f934cbe93a7d/content/spaces/avatar.textile?plain=1#L9-L24) -->
  * Avatar stacks are the most common way of showing the online status of members in an application by displaying an avatar for each member. Events are emitted whenever a member enters or leaves a space, or updates their profile data. Additional information can also be provided, such as a profile picture and email address.
  *
- * Subscribe to the `space.members` namespace in order to keep your avatar stack updated in realtime.
+ * Subscribe to the space’s { @link Space.members | `members` } property in order to keep your avatar stack updated in realtime.
  *
  * ## Event types
  *
@@ -40,7 +40,7 @@ export interface MembersEventMap {
  *
  * > **Note**
  * >
- * > Members [enter](/spaces/space#enter), [leave](/spaces/space#leave), and [update](/spaces/space#update-profile) a [space](/spaces/space) directly. The `members` namespace is used to subscribe to these updates.
+ * > Members [enter](/spaces/space#enter), [leave](/spaces/space#leave), and [update](/spaces/space#update-profile) a [space](/spaces/space) directly. The space’s { @link Space.members | `members` } property is used to subscribe to these updates.
  *
  * <!-- END WEBSITE DOCUMENTATION -->
  *
diff --git a/src/Space.ts b/src/Space.ts
index 71d6001c..a325a94d 100644
--- a/src/Space.ts
+++ b/src/Space.ts
@@ -48,9 +48,9 @@ export interface SpaceEventMap {
  * - [Live cursors](/spaces/cursors)
  * - [Component locking](/spaces/locking)
  *
- * 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.
+ * A `Space` instance 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 {@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.
+ * Space state can be {@link subscribe | subscribed} to by using a `Space` object. 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.
  *
@@ -388,7 +388,7 @@ class Space extends EventEmitter<SpaceEventMap> {
    *
    * > **Note**
    * >
-   * > [Avatar stacks](/spaces/members) and [member location](/spaces/locations) events can be subscribed to on their individual namespaces; `space.members` and `space.locations`. These events are filtered versions of space state events. Only a single [message](https://ably.com/docs/channels/messages) is published per event by Ably, irrespective of whether you register listeners for space state or individual namespaces. If you register listeners for both, it is still only a single message.
+   * > [Avatar stacks](/spaces/members) and [member location](/spaces/locations) events can be subscribed to using the space’s {@link members | `members` } and {@link locations | `locations` } properties. These events are filtered versions of space state events. Only a single [message](https://ably.com/docs/channels/messages) is published per event by Ably, irrespective of whether you register listeners for space state or individual namespaces. If you register listeners for both, it is still only a single message.
    * >
    * > The key difference between the subscribing to space state or to individual feature events, is that space state events return the current state of the space as an array of all members in each event payload. Individual member and location event payloads only include the relevant data for the member that triggered the event.
    *

From e2b99716606dd3fddf6c7f812ab451759001d259 Mon Sep 17 00:00:00 2001
From: Lawrence Forooghian <lawrence@forooghian.com>
Date: Tue, 26 Sep 2023 15:19:18 -0300
Subject: [PATCH 27/30] (WIP) Move parts of documentation to more appropriate
 places

---
 src/Cursors.ts   | 11 +++------
 src/Locations.ts | 21 +++++++++--------
 src/Locks.ts     | 27 +++++-----------------
 src/Members.ts   | 30 +++++++++++++++---------
 src/Space.ts     |  4 +++-
 src/types.ts     | 60 ++++++++++++++++++++++++++++++++++++++++++++++++
 6 files changed, 102 insertions(+), 51 deletions(-)

diff --git a/src/Cursors.ts b/src/Cursors.ts
index 02df595c..1b3ca68d 100644
--- a/src/Cursors.ts
+++ b/src/Cursors.ts
@@ -138,14 +138,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 -->
    *
diff --git a/src/Locations.ts b/src/Locations.ts
index 82442138..85f8a9b9 100644
--- a/src/Locations.ts
+++ b/src/Locations.ts
@@ -9,7 +9,15 @@ 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;
   }
 }
@@ -179,16 +187,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**
    * >
diff --git a/src/Locks.ts b/src/Locks.ts
index ddcc4ea1..c01710b8 100644
--- a/src/Locks.ts
+++ b/src/Locks.ts
@@ -55,14 +55,9 @@ export interface LocksEventMap {
  *
  * 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:
  *
@@ -500,19 +495,9 @@ 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 one of `locked`, `unlocked` or `pending`.                                   | 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 }.
    *
    * <!-- END WEBSITE DOCUMENTATION -->
    *
diff --git a/src/Members.ts b/src/Members.ts
index a5256383..c85a71f9 100644
--- a/src/Members.ts
+++ b/src/Members.ts
@@ -6,10 +6,26 @@ import type { PresenceMember } from './utilities/types.js';
 import type Space from './Space.js';
 
 export interface MembersEventMap {
+  /**
+   * <!-- 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;
+  /**
+   * <!-- MOVED 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;
 }
 
@@ -26,17 +42,9 @@ export interface MembersEventMap {
  *
  * 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**
  * >
diff --git a/src/Space.ts b/src/Space.ts
index a325a94d..b767d8b5 100644
--- a/src/Space.ts
+++ b/src/Space.ts
@@ -196,7 +196,9 @@ class Space extends EventEmitter<SpaceEventMap> {
    * >
    * > The following documentation is copied from the [Spaces documentation website](https://ably.com/docs/spaces).
    * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/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.
    *
diff --git a/src/types.ts b/src/types.ts
index 63968b9f..6fa6a973 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -51,7 +51,15 @@ export interface CursorsOptions {
  * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
  */
 export interface CursorPosition {
+  /**
+   * <!-- MOVED FROM Cursors.set -->
+   * The position of the member’s cursor on the X-axis.
+   */
   x: number;
+  /**
+   * <!-- MOVED FROM Cursors.set -->
+   * The position of the member’s cursor on the Y-axis.
+   */
   y: number;
 }
 
@@ -88,9 +96,25 @@ export type CursorData = Record<string, unknown>;
  * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
  */
 export interface CursorUpdate {
+  /**
+   * <!-- MOVED FROM Cursors.set -->
+   * The [client identifier](https://ably.com/docs/auth/identified-clients) for the member.
+   */
   clientId: string;
+  /**
+   * <!-- MOVED FROM Cursors.set -->
+   * The unique identifier of the member’s [connection](https://ably.com/docs/connect).
+   */
   connectionId: string;
+  /**
+   * <!-- MOVED FROM Cursors.set -->
+   * An object containing the position of a member’s cursor.
+   */
   position: CursorPosition;
+  /**
+   * <!-- MOVED FROM Cursors.set -->
+   * An optional arbitrary JSON-serializable object containing additional information about the cursor.
+   */
   data?: CursorData;
 }
 
@@ -130,6 +154,10 @@ export interface SpaceOptions {
   cursors: CursorsOptions;
 }
 
+/**
+ * <!-- MOVED WITH EDITING FROM Space.enter -->
+ * Profile data can be set when {@link Space.enter | entering } 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.
+ */
 export type ProfileData = Record<string, unknown> | null;
 
 /**
@@ -212,8 +240,20 @@ export interface SpaceMember {
 }
 
 export namespace LockStatuses {
+  /**
+   * <!-- COPIED WITH EDITS FROM Locks -->
+   * A member has requested a lock by calling { @link Locks.acquire | `acquire()` }.
+   */
   export type Pending = 'pending';
+  /**
+   * <!-- MOVED FROM Locks -->
+   * The lock is confirmed to be held by the requesting member.
+   */
   export type Locked = 'locked';
+  /**
+   * <!-- COPIED WITH EDITS FROM Locks -->
+   * The lock is confirmed to not be locked by the requesting member, or has been { @link Locks.release | released } by a member previously holding the lock.
+   */
   export type Unlocked = 'unlocked';
 }
 
@@ -251,10 +291,30 @@ export type LockStatus = LockStatuses.Pending | LockStatuses.Locked | LockStatus
  * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
  */
 export type Lock = {
+  /**
+   * <!-- MOVED FROM Locks.subscribe -->
+   * The unique ID of the lock request.
+   */
   id: string;
+  /**
+   * <!-- COPIED WITH EDITS FROM Locks.subscribe -->
+   * The lock status of the event.
+   */
   status: LockStatus;
   member: SpaceMember;
+  /**
+   * <!-- MOVED FROM Locks.subscribe -->
+   * The timestamp of the lock event.
+   */
   timestamp: number;
+  /**
+   * <!-- MOVED FROM Locks.subscribe -->
+   * The optional attributes of the lock, such as the ID of the component it relates to.
+   */
   attributes?: LockAttributes;
+  /**
+   * <!-- MOVED FROM Locks.subscribe -->
+   * The reason why the `request.status` is `unlocked`.
+   */
   reason?: Types.ErrorInfo;
 };

From 465245989e2822b262199762c9f6e6cfb0fd2869 Mon Sep 17 00:00:00 2001
From: Lawrence Forooghian <lawrence@forooghian.com>
Date: Tue, 26 Sep 2023 15:20:29 -0300
Subject: [PATCH 28/30] (WIP) Write documentation where none currently exists

---
 src/Cursors.ts                | 17 +++++++++++++++++
 src/Locations.ts              | 17 +++++++++++++++++
 src/Locks.ts                  | 17 +++++++++++++++++
 src/Members.ts                | 17 +++++++++++++++++
 src/Space.ts                  | 19 +++++++++++++++++++
 src/types.ts                  |  6 ++++++
 src/utilities/EventEmitter.ts | 16 ++++++++++++++++
 src/utilities/types.ts        |  3 +++
 8 files changed, 112 insertions(+)

diff --git a/src/Cursors.ts b/src/Cursors.ts
index 1b3ca68d..2f43ccca 100644
--- a/src/Cursors.ts
+++ b/src/Cursors.ts
@@ -11,6 +11,9 @@ import type { CursorsOptions, CursorUpdate } from './types.js';
 import type { RealtimeMessage } from './utilities/types.js';
 import { ERR_NOT_ENTERED_SPACE } from './Errors.js';
 
+/**
+ * The property names of `CursorsEventMap` are the names of the events emitted by { @link Cursors }.
+ */
 export interface CursorsEventMap {
   update: CursorUpdate;
 }
@@ -220,6 +223,8 @@ export default class Cursors extends EventEmitter<CursorsEventMap> {
   };
 
   /**
+   * {@label WITH_EVENTS}
+   *
    * > **Documentation source**
    * >
    * > The following documentation is copied from the [Spaces documentation website](https://ably.com/docs/spaces).
@@ -255,11 +260,16 @@ export default class Cursors extends EventEmitter<CursorsEventMap> {
    *   space.cursors.subscribe('update', (cursorUpdate: CursorUpdate) => {});
    *   ```
    * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
+   *
+   * @typeParam K A type which allows one or more names of the properties of the {@link CursorsEventMap} type.
    */
   subscribe<K extends keyof CursorsEventMap>(
     eventOrEvents: K | K[],
     listener?: EventListener<CursorsEventMap, 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(listener?: EventListener<CursorsEventMap, keyof CursorsEventMap>): void;
   subscribe<K extends keyof CursorsEventMap>(
     listenerOrEvents?: K | K[] | EventListener<CursorsEventMap, K>,
@@ -287,6 +297,8 @@ export default class Cursors extends EventEmitter<CursorsEventMap> {
   }
 
   /**
+   * {@label WITH_EVENTS}
+   *
    * > **Documentation source**
    * >
    * > The following documentation is copied from the [Spaces documentation website](https://ably.com/docs/spaces).
@@ -315,11 +327,16 @@ export default class Cursors extends EventEmitter<CursorsEventMap> {
    * space.cursors.unsubscribe('update');
    * ```
    * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
+   *
+   * @typeParam K A type which allows one or more names of the properties of the {@link CursorsEventMap} type.
    */
   unsubscribe<K extends keyof CursorsEventMap>(
     eventOrEvents: K | K[],
     listener?: EventListener<CursorsEventMap, K>,
   ): void;
+  /**
+   * Behaves the same as { @link unsubscribe:WITH_EVENTS | the overload which accepts one or more event names }, but subscribes to _all_ events.
+   */
   unsubscribe(listener?: EventListener<CursorsEventMap, keyof CursorsEventMap>): void;
   unsubscribe<K extends keyof CursorsEventMap>(
     listenerOrEvents?: K | K[] | EventListener<CursorsEventMap, K>,
diff --git a/src/Locations.ts b/src/Locations.ts
index 85f8a9b9..4094708b 100644
--- a/src/Locations.ts
+++ b/src/Locations.ts
@@ -22,6 +22,9 @@ export namespace LocationsEvents {
   }
 }
 
+/**
+ * The property names of `LocationsEventMap` are the names of the events emitted by { @link Locations }.
+ */
 export interface LocationsEventMap {
   update: LocationsEvents.UpdateEvent;
 }
@@ -135,6 +138,8 @@ export default class Locations extends EventEmitter<LocationsEventMap> {
   }
 
   /**
+   * {@label WITH_EVENTS}
+   *
    * > **Documentation source**
    * >
    * > The following documentation is copied from the [Spaces documentation website](https://ably.com/docs/spaces).
@@ -213,11 +218,16 @@ export default class Locations extends EventEmitter<LocationsEventMap> {
    *   space.locations.subscribe('update', (locationUpdate: LocationUpdate) => {});
    *   ```
    * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
+   *
+   * @typeParam K A type which allows one or more names of the properties of the {@link LocationsEventMap} type.
    */
   subscribe<K extends keyof LocationsEventMap>(
     eventOrEvents: K | K[],
     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(listener?: EventListener<LocationsEventMap, keyof LocationsEventMap>): void;
   subscribe<K extends keyof LocationsEventMap>(
     listenerOrEvents?: K | K[] | EventListener<LocationsEventMap, K>,
@@ -237,6 +247,8 @@ export default class Locations extends EventEmitter<LocationsEventMap> {
   }
 
   /**
+   * {@label WITH_EVENTS}
+   *
    * > **Documentation source**
    * >
    * > The following documentation is copied from the [Spaces documentation website](https://ably.com/docs/spaces).
@@ -265,11 +277,16 @@ export default class Locations extends EventEmitter<LocationsEventMap> {
    * space.locations.unsubscribe('update');
    * ```
    * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
+   *
+   * @typeParam K A type which allows one or more names of the properties of the {@link LocationsEventMap} type.
    */
   unsubscribe<K extends keyof LocationsEventMap>(
     eventOrEvents: K | K[],
     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(listener?: EventListener<LocationsEventMap, keyof LocationsEventMap>): void;
   unsubscribe<K extends keyof LocationsEventMap>(
     listenerOrEvents?: K | K[] | EventListener<LocationsEventMap, K>,
diff --git a/src/Locks.ts b/src/Locks.ts
index c01710b8..7c335b91 100644
--- a/src/Locks.ts
+++ b/src/Locks.ts
@@ -30,6 +30,9 @@ export interface LockOptions {
   attributes: LockAttributes;
 }
 
+/**
+ * The property names of `LocksEventMap` are the names of the events emitted by { @link Locks }.
+ */
 export interface LocksEventMap {
   update: Lock;
 }
@@ -445,6 +448,8 @@ export default class Locks extends EventEmitter<LocksEventMap> {
   }
 
   /**
+   * {@label WITH_EVENTS}
+   *
    * > **Documentation source**
    * >
    * > The following documentation is copied from the [Spaces documentation website](https://ably.com/docs/spaces).
@@ -519,8 +524,13 @@ export default class Locks extends EventEmitter<LocksEventMap> {
    *
    *   The argument supplied to the callback is a [Lock](#lock), representing the lock request and it's status.
    * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
+   *
+   * @typeParam K A type which allows one or more names of the properties of the {@link LocksEventMap} type.
    */
   subscribe<K extends keyof LocksEventMap>(eventOrEvents: K | K[], listener?: EventListener<LocksEventMap, 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(listener?: EventListener<LocksEventMap, keyof LocksEventMap>): void;
   subscribe<K extends keyof LocksEventMap>(
     listenerOrEvents?: K | K[] | EventListener<LocksEventMap, K>,
@@ -540,6 +550,8 @@ export default class Locks extends EventEmitter<LocksEventMap> {
   }
 
   /**
+   * {@label WITH_EVENTS}
+   *
    * > **Documentation source**
    * >
    * > The following documentation is copied from the [Spaces documentation website](https://ably.com/docs/spaces).
@@ -568,8 +580,13 @@ export default class Locks extends EventEmitter<LocksEventMap> {
    * space.locks.unsubscribe('update');
    * ```
    * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
+   *
+   * @typeParam K A type which allows one or more names of the properties of the {@link LocksEventMap} type.
    */
   unsubscribe<K extends keyof LocksEventMap>(eventOrEvents: K | K[], listener?: EventListener<LocksEventMap, 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(listener?: EventListener<LocksEventMap, keyof LocksEventMap>): void;
   unsubscribe<K extends keyof LocksEventMap>(
     listenerOrEvents?: K | K[] | EventListener<LocksEventMap, K>,
diff --git a/src/Members.ts b/src/Members.ts
index c85a71f9..aa410def 100644
--- a/src/Members.ts
+++ b/src/Members.ts
@@ -5,6 +5,9 @@ import type { SpaceMember } from './types.js';
 import type { PresenceMember } from './utilities/types.js';
 import type Space from './Space.js';
 
+/**
+ * The property names of `MembersEventMap` are the names of the events emitted by { @link Members }.
+ */
 export interface MembersEventMap {
   /**
    * <!-- COPIED WITH EDITING FROM Members -->
@@ -308,6 +311,8 @@ class Members extends EventEmitter<MembersEventMap> {
   }
 
   /**
+   * {@label WITH_EVENTS}
+   *
    * > **Documentation source**
    * >
    * > The following documentation is copied from the Spaces documentation website.
@@ -451,11 +456,16 @@ class Members extends EventEmitter<MembersEventMap> {
    *
    *   The argument supplied to the callback is a [SpaceMember](#spacemember) object representing the member affected by the change.
    * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
+   *
+   * @typeParam K A type which allows one or more names of the properties of the {@link MembersEventMap} type.
    */
   subscribe<K extends keyof MembersEventMap>(
     eventOrEvents: K | K[],
     listener?: EventListener<MembersEventMap, 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(listener?: EventListener<MembersEventMap, keyof MembersEventMap>): void;
   subscribe<K extends keyof MembersEventMap>(
     listenerOrEvents?: K | K[] | EventListener<MembersEventMap, K>,
@@ -475,6 +485,8 @@ class Members extends EventEmitter<MembersEventMap> {
   }
 
   /**
+   * {@label WITH_EVENTS}
+   *
    * > **Documentation source**
    * >
    * > The following documentation is copied from the Spaces documentation website.
@@ -515,11 +527,16 @@ class Members extends EventEmitter<MembersEventMap> {
    * space.members.unsubscribe('leave');
    * ```
    * <!-- END CLASS-DEFINITIONS DOCUMENTATION -->
+   *
+   * @typeParam K A type which allows one or more names of the properties of the {@link MembersEventMap} type.
    */
   unsubscribe<K extends keyof MembersEventMap>(
     eventOrEvents: K | K[],
     listener?: EventListener<MembersEventMap, 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(listener?: EventListener<MembersEventMap, keyof MembersEventMap>): void;
   unsubscribe<K extends keyof MembersEventMap>(
     listenerOrEvents?: K | K[] | EventListener<MembersEventMap, K>,
diff --git a/src/Space.ts b/src/Space.ts
index b767d8b5..4c8d00c0 100644
--- a/src/Space.ts
+++ b/src/Space.ts
@@ -31,6 +31,9 @@ export namespace SpaceEvents {
 }
 
 export interface SpaceEventMap {
+  /**
+   * The property names of `SpaceEventMap` are the names of the events emitted by { @link Space }.
+   */
   update: SpaceEvents.UpdateEvent;
 }
 
@@ -223,6 +226,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) => {
@@ -375,6 +380,8 @@ class Space extends EventEmitter<SpaceEventMap> {
   }
 
   /**
+   * {@label WITH_EVENTS}
+   *
    * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/content/spaces/space.textile?plain=1#L107-L177) -->
    * Subscribe to space state updates by registering a listener. Use the `subscribe()` method on the `space` object to receive updates.
    *
@@ -449,8 +456,13 @@ class Space extends EventEmitter<SpaceEventMap> {
    * | lastEvent.timestamp | The timestamp of the most recently emitted event.                      | Number  |
    *
    * <!-- END WEBSITE DOCUMENTATION -->
+   *
+   * @typeParam K A type which allows one or more names of the properties of the {@link SpaceEventMap} type.
    */
   subscribe<K extends keyof SpaceEventMap>(eventOrEvents: K | K[], listener?: EventListener<SpaceEventMap, 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(listener?: EventListener<SpaceEventMap, keyof SpaceEventMap>): void;
   subscribe<K extends keyof SpaceEventMap>(
     listenerOrEvents?: K | K[] | EventListener<SpaceEventMap, K>,
@@ -470,6 +482,8 @@ class Space extends EventEmitter<SpaceEventMap> {
   }
 
   /**
+   * {@label WITH_EVENTS}
+   *
    * <!-- BEGIN WEBSITE DOCUMENTATION (https://github.com/ably/docs/blob/5f9e999399ebf284c0eeecff52a9d1e4d36ce8a8/content/spaces/space.textile?plain=1#L181-L187) -->
    * Unsubscribe from space events to remove previously registered listeners.
    *
@@ -479,8 +493,13 @@ class Space extends EventEmitter<SpaceEventMap> {
    * space.unsubscribe('update', listener);
    * ```
    * <!-- END WEBSITE DOCUMENTATION -->
+   *
+   * @typeParam K A type which allows one or more names of the properties of the {@link SpaceEventMap} type.
    */
   unsubscribe<K extends keyof SpaceEventMap>(eventOrEvents: K | K[], listener?: EventListener<SpaceEventMap, 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(listener?: EventListener<SpaceEventMap, keyof SpaceEventMap>): void;
   unsubscribe<K extends keyof SpaceEventMap>(
     listenerOrEvents?: K | K[] | EventListener<SpaceEventMap, K>,
diff --git a/src/types.ts b/src/types.ts
index 6fa6a973..068109f2 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -239,6 +239,9 @@ export interface SpaceMember {
   };
 }
 
+/**
+ * The `LockStatuses` namespace describes the possible values of the {@link LockStatus} type.
+ */
 export namespace LockStatuses {
   /**
    * <!-- COPIED WITH EDITS FROM Locks -->
@@ -301,6 +304,9 @@ export type Lock = {
    * The lock status of the event.
    */
   status: LockStatus;
+  /**
+   * Information about the space member who requested the lock.
+   */
   member: SpaceMember;
   /**
    * <!-- MOVED FROM Locks.subscribe -->
diff --git a/src/utilities/EventEmitter.ts b/src/utilities/EventEmitter.ts
index b6a3d813..3d08ca27 100644
--- a/src/utilities/EventEmitter.ts
+++ b/src/utilities/EventEmitter.ts
@@ -64,8 +64,15 @@ export class InvalidArgumentError extends Error {
   }
 }
 
+/**
+ * @typeParam T The type of event data that this listener will receive.
+ * @typeParam K The name of the event that this listener will listen for.
+ */
 export type EventListener<T, K extends keyof T> = (this: { event: K }, param: T[K]) => void;
 
+/**
+ * @typeParam T An object type, the names of whose properties are the names of the events that an instance of this class can emit.
+ */
 export default class EventEmitter<T> {
   /** @internal */
   any: Array<Function>;
@@ -78,6 +85,7 @@ export default class EventEmitter<T> {
 
   /**
    * @internal
+   * @typeParam T An object type, the names of whose properties are the names of the events that the constructed object can emit.
    */
   constructor() {
     this.any = [];
@@ -91,6 +99,8 @@ export default class EventEmitter<T> {
    * Add an event listener
    * @param eventOrEvents the name of the event to listen to or the listener to be called.
    * @param listener (optional) the listener to be called.
+   *
+   * @typeParam K A type which allows one or more names of the properties of {@link T}.
    */
   on<K extends keyof T>(eventOrEvents?: K | K[], listener?: EventListener<T, K>): void;
   /**
@@ -133,6 +143,8 @@ export default class EventEmitter<T> {
    * Remove one or more event listeners
    * @param eventOrEvents the name of the event whose listener is to be removed.
    * @param listener (optional) the listener to remove. If not supplied, all listeners are removed.
+   *
+   * @typeParam K A type which allows one or more names of the properties of {@link T}. TypeScript will infer this type based on the {@link eventOrEvents} argument.
    */
   off<K extends keyof T>(eventOrEvents?: K | K[], listener?: EventListener<T, K>): void;
   /**
@@ -199,6 +211,8 @@ export default class EventEmitter<T> {
    * Get the array of listeners for a given event; excludes once events
    * @param event (optional) the name of the event, or none for 'any'
    * @return array of events, or null if none
+   *
+   * @typeParam K A type which allows a name of the properties of {@link T}. TypeScript will infer this type based on the {@link event} argument.
    */
   listeners<K extends keyof T>(event: K): Function[] | null {
     if (event) {
@@ -255,6 +269,8 @@ export default class EventEmitter<T> {
    * Listen for a single occurrence of an event
    * @param event the name of the event to listen to
    * @param listener (optional) the listener to be called
+   *
+   * @typeParam K A type which allows a name of one of the properties of {@link T}. TypeScript will infer this type based on the {@link event} argument.
    */
   once<K extends keyof T>(event: K, listener?: EventListener<T, K>): void | Promise<any>;
   /**
diff --git a/src/utilities/types.ts b/src/utilities/types.ts
index e1896cbf..ba3cfe99 100644
--- a/src/utilities/types.ts
+++ b/src/utilities/types.ts
@@ -19,6 +19,9 @@ export type PresenceMember = {
   };
 } & Omit<Types.PresenceMessage, 'data'>;
 
+/**
+ * @typeParam K The type from which `Subset` is derived.
+ */
 export type Subset<K> = {
   [attr in keyof K]?: K[attr] extends object ? Subset<K[attr]> : K[attr];
 };

From 84dae0561934a4a27f0f8c3b138077f49e612e4e Mon Sep 17 00:00:00 2001
From: Lawrence Forooghian <lawrence@forooghian.com>
Date: Mon, 18 Sep 2023 10:31:29 -0300
Subject: [PATCH 29/30] (WIP) Use TypeDoc to generate HTML documentation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

This is largely copied from the way we do things in ably-js (as of its
commit 76a5475).

I’ve made a couple of tweaks to the config, though:

- Added all types (except Project, which I have no idea how to
  document) to requiredToBeDocumented. I took the list from [1].

  TODO what about return values? Is there a way to make TypeDoc complain
  if they’re not documented?

- Excluded internal and private stuff from documentation (see ccafd10).

[1] https://github.com/TypeStrong/typedoc/blob/f2d2abe054feca91b89c00c33e1d726bbda85dcb/src/lib/models/reflections/kind.ts#L7
---
 .github/workflows/dev-ci.yml |  28 ++++++
 .gitignore                   |   1 +
 docs/typedoc/intro.md        |   7 ++
 package-lock.json            | 168 ++++++++++++++++++++++++++++++++---
 package.json                 |   6 +-
 typedoc.json                 |  35 ++++++++
 6 files changed, 231 insertions(+), 14 deletions(-)
 create mode 100644 docs/typedoc/intro.md
 create mode 100644 typedoc.json

diff --git a/.github/workflows/dev-ci.yml b/.github/workflows/dev-ci.yml
index 1d5da735..d78aa820 100644
--- a/.github/workflows/dev-ci.yml
+++ b/.github/workflows/dev-ci.yml
@@ -52,3 +52,31 @@ jobs:
           node-version: 18
       - run: npm ci
       - run: npm run build
+  docs:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      deployments: write
+    steps:
+      - uses: actions/checkout@v2
+      - uses: actions/setup-node@v1
+        with:
+          node-version: 18
+      - name: Install Package Dependencies
+        run: npm ci
+      - name: Build SDK
+        run: npm run build
+      - name: Build Documentation
+        run: npm run docs
+      - name: Configure AWS Credentials
+        uses: aws-actions/configure-aws-credentials@v1
+        with:
+          aws-region: eu-west-2
+          role-to-assume: arn:aws:iam::${{ secrets.ABLY_AWS_ACCOUNT_ID_SDK }}:role/ably-sdk-builds-spaces
+          role-session-name: "${{ github.run_id }}-${{ github.run_number }}"
+      - name: Upload Documentation
+        uses: ably/sdk-upload-action@v1
+        with:
+          sourcePath: docs/typedoc/generated
+          githubToken: ${{ secrets.GITHUB_TOKEN }}
+          artifactName: typedoc
diff --git a/.gitignore b/.gitignore
index 2a5c1164..d5382a82 100644
--- a/.gitignore
+++ b/.gitignore
@@ -5,6 +5,7 @@ node_modules/
 .vscode
 coverage
 .env
+docs/typedoc/generated/
 
 # Local Netlify folder
 .netlify
diff --git a/docs/typedoc/intro.md b/docs/typedoc/intro.md
new file mode 100644
index 00000000..710857ab
--- /dev/null
+++ b/docs/typedoc/intro.md
@@ -0,0 +1,7 @@
+# Ably Spaces SDK
+
+<!-- TODO needs proper content -->
+
+This is the documentation for Ably’s Spaces SDK. Start with the documentation for the SDK’s {@link default | default export}.
+
+For alternative documentation, see our [documentation website](https://ably.com/docs/spaces).
diff --git a/package-lock.json b/package-lock.json
index 9850a22d..4e94a9b1 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -9,7 +9,8 @@
       "version": "0.1.3",
       "license": "ISC",
       "dependencies": {
-        "nanoid": "^4.0.2"
+        "nanoid": "^4.0.2",
+        "typedoc": "^0.25.1"
       },
       "devDependencies": {
         "@rollup/plugin-node-resolve": "^15.2.1",
@@ -1294,6 +1295,11 @@
         "node": ">=8"
       }
     },
+    "node_modules/ansi-sequence-parser": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/ansi-sequence-parser/-/ansi-sequence-parser-1.1.1.tgz",
+      "integrity": "sha512-vJXt3yiaUL4UU546s3rPXlsry/RnM730G1+HkpKE012AN0sx1eOrxSu95oKDIonskeLTijMgqWZ3uDEe3NFvyg=="
+    },
     "node_modules/ansi-styles": {
       "version": "4.3.0",
       "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz",
@@ -1476,8 +1482,7 @@
     "node_modules/balanced-match": {
       "version": "1.0.2",
       "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.2.tgz",
-      "integrity": "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==",
-      "dev": true
+      "integrity": "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw=="
     },
     "node_modules/base64-js": {
       "version": "1.0.2",
@@ -3338,8 +3343,7 @@
     "node_modules/jsonc-parser": {
       "version": "3.2.0",
       "resolved": "https://registry.npmjs.org/jsonc-parser/-/jsonc-parser-3.2.0.tgz",
-      "integrity": "sha512-gfFQZrcTc8CnKXp6Y4/CBT3fTc0OVuDofpre4aEeEpSBPV5X5v4+Vmx+8snU7RLPrNHPKSgLxGo9YuQzz20o+w==",
-      "dev": true
+      "integrity": "sha512-gfFQZrcTc8CnKXp6Y4/CBT3fTc0OVuDofpre4aEeEpSBPV5X5v4+Vmx+8snU7RLPrNHPKSgLxGo9YuQzz20o+w=="
     },
     "node_modules/keyv": {
       "version": "4.5.2",
@@ -3426,6 +3430,11 @@
         "node": ">=10"
       }
     },
+    "node_modules/lunr": {
+      "version": "2.3.9",
+      "resolved": "https://registry.npmjs.org/lunr/-/lunr-2.3.9.tgz",
+      "integrity": "sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow=="
+    },
     "node_modules/magic-string": {
       "version": "0.30.3",
       "resolved": "https://registry.npmjs.org/magic-string/-/magic-string-0.30.3.tgz",
@@ -3465,6 +3474,17 @@
       "integrity": "sha512-s8UhlNe7vPKomQhC1qFelMokr/Sc3AgNbso3n74mVPA5LTZwkB9NlXf4XPamLxJE8h0gh73rM94xvwRT2CVInw==",
       "dev": true
     },
+    "node_modules/marked": {
+      "version": "4.3.0",
+      "resolved": "https://registry.npmjs.org/marked/-/marked-4.3.0.tgz",
+      "integrity": "sha512-PRsaiG84bK+AMvxziE/lCFss8juXjNaWzVbN5tXAm4XjeaS9NAHhop+PjQxz2A9h8Q4M/xGmzP8vqNwy6JeK0A==",
+      "bin": {
+        "marked": "bin/marked.js"
+      },
+      "engines": {
+        "node": ">= 12"
+      }
+    },
     "node_modules/merge2": {
       "version": "1.4.1",
       "resolved": "https://registry.npmjs.org/merge2/-/merge2-1.4.1.tgz",
@@ -4270,6 +4290,17 @@
         "node": ">=8"
       }
     },
+    "node_modules/shiki": {
+      "version": "0.14.4",
+      "resolved": "https://registry.npmjs.org/shiki/-/shiki-0.14.4.tgz",
+      "integrity": "sha512-IXCRip2IQzKwxArNNq1S+On4KPML3Yyn8Zzs/xRgcgOWIr8ntIK3IKzjFPfjy/7kt9ZMjc+FItfqHRBg8b6tNQ==",
+      "dependencies": {
+        "ansi-sequence-parser": "^1.1.0",
+        "jsonc-parser": "^3.2.0",
+        "vscode-oniguruma": "^1.7.0",
+        "vscode-textmate": "^8.0.0"
+      }
+    },
     "node_modules/side-channel": {
       "version": "1.0.4",
       "resolved": "https://registry.npmjs.org/side-channel/-/side-channel-1.0.4.tgz",
@@ -4755,11 +4786,52 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/typedoc": {
+      "version": "0.25.1",
+      "resolved": "https://registry.npmjs.org/typedoc/-/typedoc-0.25.1.tgz",
+      "integrity": "sha512-c2ye3YUtGIadxN2O6YwPEXgrZcvhlZ6HlhWZ8jQRNzwLPn2ylhdGqdR8HbyDRyALP8J6lmSANILCkkIdNPFxqA==",
+      "dependencies": {
+        "lunr": "^2.3.9",
+        "marked": "^4.3.0",
+        "minimatch": "^9.0.3",
+        "shiki": "^0.14.1"
+      },
+      "bin": {
+        "typedoc": "bin/typedoc"
+      },
+      "engines": {
+        "node": ">= 16"
+      },
+      "peerDependencies": {
+        "typescript": "4.6.x || 4.7.x || 4.8.x || 4.9.x || 5.0.x || 5.1.x || 5.2.x"
+      }
+    },
+    "node_modules/typedoc/node_modules/brace-expansion": {
+      "version": "2.0.1",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.1.tgz",
+      "integrity": "sha512-XnAIvQ8eM+kC6aULx6wuQiwVsnzsi9d3WxzV3FpWTGA19F621kwdbsAcFKXgKUHZWsy+mY6iL1sHTxWEFCytDA==",
+      "dependencies": {
+        "balanced-match": "^1.0.0"
+      }
+    },
+    "node_modules/typedoc/node_modules/minimatch": {
+      "version": "9.0.3",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-9.0.3.tgz",
+      "integrity": "sha512-RHiac9mvaRw0x3AYRgDC1CxAP7HTcNrrECeA8YYJeWnpo+2Q5CegtZjaotWTWxDG3UeGA1coE05iH1mPjT/2mg==",
+      "dependencies": {
+        "brace-expansion": "^2.0.1"
+      },
+      "engines": {
+        "node": ">=16 || 14 >=14.17"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
+      }
+    },
     "node_modules/typescript": {
       "version": "4.9.5",
       "resolved": "https://registry.npmjs.org/typescript/-/typescript-4.9.5.tgz",
       "integrity": "sha512-1FXk9E2Hm+QzZQ7z+McJiHL4NW1F2EzMu9Nq9i3zAaGqibafqYwCVU6WyWAuyQRRzOlxou8xZSyXLEN8oKj24g==",
-      "dev": true,
       "bin": {
         "tsc": "bin/tsc",
         "tsserver": "bin/tsserver"
@@ -4982,6 +5054,16 @@
         "node": ">=14.0.0"
       }
     },
+    "node_modules/vscode-oniguruma": {
+      "version": "1.7.0",
+      "resolved": "https://registry.npmjs.org/vscode-oniguruma/-/vscode-oniguruma-1.7.0.tgz",
+      "integrity": "sha512-L9WMGRfrjOhgHSdOYgCt/yRMsXzLDJSL7BPrOZt73gU0iWO4mpqzqQzOz5srxqTvMBaR0XZTSrVWo4j55Rc6cA=="
+    },
+    "node_modules/vscode-textmate": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/vscode-textmate/-/vscode-textmate-8.0.0.tgz",
+      "integrity": "sha512-AFbieoL7a5LMqcnOF04ji+rpXadgOXnZsxQr//r83kLPr7biP7am3g9zbaZIaBGwBRWeSvoMD4mgPdX3e4NWBg=="
+    },
     "node_modules/which": {
       "version": "2.0.2",
       "resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz",
@@ -5941,6 +6023,11 @@
       "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==",
       "dev": true
     },
+    "ansi-sequence-parser": {
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/ansi-sequence-parser/-/ansi-sequence-parser-1.1.1.tgz",
+      "integrity": "sha512-vJXt3yiaUL4UU546s3rPXlsry/RnM730G1+HkpKE012AN0sx1eOrxSu95oKDIonskeLTijMgqWZ3uDEe3NFvyg=="
+    },
     "ansi-styles": {
       "version": "4.3.0",
       "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-4.3.0.tgz",
@@ -6069,8 +6156,7 @@
     "balanced-match": {
       "version": "1.0.2",
       "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-1.0.2.tgz",
-      "integrity": "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw==",
-      "dev": true
+      "integrity": "sha512-3oSeUO0TMV67hN1AmbXsK4yaqU7tjiHlbxRDZOpH0KW9+CeX4bRAaX0Anxt0tx2MrpRpWwQaPwIlISEJhYU5Pw=="
     },
     "base64-js": {
       "version": "1.0.2",
@@ -7466,8 +7552,7 @@
     "jsonc-parser": {
       "version": "3.2.0",
       "resolved": "https://registry.npmjs.org/jsonc-parser/-/jsonc-parser-3.2.0.tgz",
-      "integrity": "sha512-gfFQZrcTc8CnKXp6Y4/CBT3fTc0OVuDofpre4aEeEpSBPV5X5v4+Vmx+8snU7RLPrNHPKSgLxGo9YuQzz20o+w==",
-      "dev": true
+      "integrity": "sha512-gfFQZrcTc8CnKXp6Y4/CBT3fTc0OVuDofpre4aEeEpSBPV5X5v4+Vmx+8snU7RLPrNHPKSgLxGo9YuQzz20o+w=="
     },
     "keyv": {
       "version": "4.5.2",
@@ -7533,6 +7618,11 @@
         "yallist": "^4.0.0"
       }
     },
+    "lunr": {
+      "version": "2.3.9",
+      "resolved": "https://registry.npmjs.org/lunr/-/lunr-2.3.9.tgz",
+      "integrity": "sha512-zTU3DaZaF3Rt9rhN3uBMGQD3dD2/vFQqnvZCDv4dl5iOzq2IZQqTxu90r4E5J+nP70J3ilqVCrbho2eWaeW8Ow=="
+    },
     "magic-string": {
       "version": "0.30.3",
       "resolved": "https://registry.npmjs.org/magic-string/-/magic-string-0.30.3.tgz",
@@ -7565,6 +7655,11 @@
       "integrity": "sha512-s8UhlNe7vPKomQhC1qFelMokr/Sc3AgNbso3n74mVPA5LTZwkB9NlXf4XPamLxJE8h0gh73rM94xvwRT2CVInw==",
       "dev": true
     },
+    "marked": {
+      "version": "4.3.0",
+      "resolved": "https://registry.npmjs.org/marked/-/marked-4.3.0.tgz",
+      "integrity": "sha512-PRsaiG84bK+AMvxziE/lCFss8juXjNaWzVbN5tXAm4XjeaS9NAHhop+PjQxz2A9h8Q4M/xGmzP8vqNwy6JeK0A=="
+    },
     "merge2": {
       "version": "1.4.1",
       "resolved": "https://registry.npmjs.org/merge2/-/merge2-1.4.1.tgz",
@@ -8096,6 +8191,17 @@
       "integrity": "sha512-7++dFhtcx3353uBaq8DDR4NuxBetBzC7ZQOhmTQInHEd6bSrXdiEyzCvG07Z44UYdLShWUyXt5M/yhz8ekcb1A==",
       "dev": true
     },
+    "shiki": {
+      "version": "0.14.4",
+      "resolved": "https://registry.npmjs.org/shiki/-/shiki-0.14.4.tgz",
+      "integrity": "sha512-IXCRip2IQzKwxArNNq1S+On4KPML3Yyn8Zzs/xRgcgOWIr8ntIK3IKzjFPfjy/7kt9ZMjc+FItfqHRBg8b6tNQ==",
+      "requires": {
+        "ansi-sequence-parser": "^1.1.0",
+        "jsonc-parser": "^3.2.0",
+        "vscode-oniguruma": "^1.7.0",
+        "vscode-textmate": "^8.0.0"
+      }
+    },
     "side-channel": {
       "version": "1.0.4",
       "resolved": "https://registry.npmjs.org/side-channel/-/side-channel-1.0.4.tgz",
@@ -8456,11 +8562,39 @@
         "is-typed-array": "^1.1.9"
       }
     },
+    "typedoc": {
+      "version": "0.25.1",
+      "resolved": "https://registry.npmjs.org/typedoc/-/typedoc-0.25.1.tgz",
+      "integrity": "sha512-c2ye3YUtGIadxN2O6YwPEXgrZcvhlZ6HlhWZ8jQRNzwLPn2ylhdGqdR8HbyDRyALP8J6lmSANILCkkIdNPFxqA==",
+      "requires": {
+        "lunr": "^2.3.9",
+        "marked": "^4.3.0",
+        "minimatch": "^9.0.3",
+        "shiki": "^0.14.1"
+      },
+      "dependencies": {
+        "brace-expansion": {
+          "version": "2.0.1",
+          "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.1.tgz",
+          "integrity": "sha512-XnAIvQ8eM+kC6aULx6wuQiwVsnzsi9d3WxzV3FpWTGA19F621kwdbsAcFKXgKUHZWsy+mY6iL1sHTxWEFCytDA==",
+          "requires": {
+            "balanced-match": "^1.0.0"
+          }
+        },
+        "minimatch": {
+          "version": "9.0.3",
+          "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-9.0.3.tgz",
+          "integrity": "sha512-RHiac9mvaRw0x3AYRgDC1CxAP7HTcNrrECeA8YYJeWnpo+2Q5CegtZjaotWTWxDG3UeGA1coE05iH1mPjT/2mg==",
+          "requires": {
+            "brace-expansion": "^2.0.1"
+          }
+        }
+      }
+    },
     "typescript": {
       "version": "4.9.5",
       "resolved": "https://registry.npmjs.org/typescript/-/typescript-4.9.5.tgz",
-      "integrity": "sha512-1FXk9E2Hm+QzZQ7z+McJiHL4NW1F2EzMu9Nq9i3zAaGqibafqYwCVU6WyWAuyQRRzOlxou8xZSyXLEN8oKj24g==",
-      "dev": true
+      "integrity": "sha512-1FXk9E2Hm+QzZQ7z+McJiHL4NW1F2EzMu9Nq9i3zAaGqibafqYwCVU6WyWAuyQRRzOlxou8xZSyXLEN8oKj24g=="
     },
     "ufo": {
       "version": "1.3.0",
@@ -8572,6 +8706,16 @@
         }
       }
     },
+    "vscode-oniguruma": {
+      "version": "1.7.0",
+      "resolved": "https://registry.npmjs.org/vscode-oniguruma/-/vscode-oniguruma-1.7.0.tgz",
+      "integrity": "sha512-L9WMGRfrjOhgHSdOYgCt/yRMsXzLDJSL7BPrOZt73gU0iWO4mpqzqQzOz5srxqTvMBaR0XZTSrVWo4j55Rc6cA=="
+    },
+    "vscode-textmate": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/vscode-textmate/-/vscode-textmate-8.0.0.tgz",
+      "integrity": "sha512-AFbieoL7a5LMqcnOF04ji+rpXadgOXnZsxQr//r83kLPr7biP7am3g9zbaZIaBGwBRWeSvoMD4mgPdX3e4NWBg=="
+    },
     "which": {
       "version": "2.0.2",
       "resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz",
diff --git a/package.json b/package.json
index b06ddb0a..65737e6b 100644
--- a/package.json
+++ b/package.json
@@ -19,7 +19,8 @@
     "build:cjs": "npx tsc --project tsconfig.cjs.json && cp res/package.cjs.json dist/cjs/package.json",
     "build:iife": "rm -rf dist/iife && npx tsc --project tsconfig.iife.json && rollup -c",
     "prepare": "husky install",
-    "examples:locks": "ts-node ./examples/locks.ts"
+    "examples:locks": "ts-node ./examples/locks.ts",
+    "docs": "typedoc"
   },
   "exports": {
     "import": "./dist/mjs/index.js",
@@ -57,7 +58,8 @@
     "vitest": "^0.34.3"
   },
   "dependencies": {
-    "nanoid": "^4.0.2"
+    "nanoid": "^4.0.2",
+    "typedoc": "^0.25.1"
   },
   "peerDependencies": {
     "ably": "^1.2.43"
diff --git a/typedoc.json b/typedoc.json
new file mode 100644
index 00000000..9ef0823b
--- /dev/null
+++ b/typedoc.json
@@ -0,0 +1,35 @@
+{
+  "$schema": "https://typedoc.org/schema.json",
+  "entryPoints": ["dist/mjs/index.d.ts"],
+  "excludeInternal": true,
+  "excludePrivate": true,
+  "includeVersion": true,
+  "out": "docs/typedoc/generated",
+  "readme": "docs/typedoc/intro.md",
+  "requiredToBeDocumented": [
+    "Accessor",
+    "CallSignature",
+    "Class",
+    "Constructor",
+    "ConstructorSignature",
+    "Enum",
+    "EnumMember",
+    "Function",
+    "GetSignature",
+    "IndexSignature",
+    "Interface",
+    "Method",
+    "Module",
+    "Namespace",
+    "Parameter",
+    "Property",
+    "Reference",
+    "SetSignature",
+    "TypeAlias",
+    "TypeLiteral",
+    "TypeParameter",
+    "Variable",
+  ],
+  "treatWarningsAsErrors": true,
+  "validation": true
+}

From 58266b7316bf8c2906b5c5319e27fcdcb9270bb3 Mon Sep 17 00:00:00 2001
From: Lawrence Forooghian <lawrence@forooghian.com>
Date: Wed, 20 Sep 2023 11:53:51 -0300
Subject: [PATCH 30/30] (TODO remove) Don't treat TypeDoc warnings as errors

So that I can use CI to upload a preview of the documentation.
---
 typedoc.json | 1 -
 1 file changed, 1 deletion(-)

diff --git a/typedoc.json b/typedoc.json
index 9ef0823b..9179c546 100644
--- a/typedoc.json
+++ b/typedoc.json
@@ -30,6 +30,5 @@
     "TypeParameter",
     "Variable",
   ],
-  "treatWarningsAsErrors": true,
   "validation": true
 }