@fluidframework/sequence 1.2.7 → 2.0.0-dev.1.3.0.96595

package/src/intervalCollection.ts

@@ -11,6 +11,7 @@ import { UsageError } from "@fluidframework/container-utils";
 import {
     addProperties,
     Client,
+    compareReferencePositions,
     ConflictAction,
     createMap,
     ICombiningOp,
@@ -19,15 +20,19 @@ import {
     IntervalNode,
     IntervalTree,
     ISegment,
-    LocalReference,
     MergeTreeDeltaType,
+    minReferencePosition,
     PropertiesManager,
     PropertySet,
     RedBlackTree,
+    LocalReferencePosition,
     ReferenceType,
     refTypeIncludesFlag,
     reservedRangeLabelsKey,
     UnassignedSequenceNumber,
+    maxReferencePosition,
+    createDetachedLocalReferencePosition,
+    DetachedReferencePosition,
 } from "@fluidframework/merge-tree";
 import { ISequencedDocumentMessage } from "@fluidframework/protocol-definitions";
 import { LoggingError } from "@fluidframework/telemetry-utils";
@@ -46,6 +51,7 @@ const reservedIntervalIdKey = "intervalId";
 export enum IntervalType {
     Simple = 0x0,
     Nest = 0x1,
+
     /**
      * SlideOnRemove indicates that the ends of the interval will slide if the segment
      * they reference is removed and acked.
@@ -53,9 +59,10 @@ export enum IntervalType {
      * SlideOnRemove is the default interval behavior and does not need to be specified.
      */
     SlideOnRemove = 0x2, // SlideOnRemove is default behavior - all intervals are SlideOnRemove
+
     /**
-     * @internal
      * A temporary interval, used internally
+     * @internal
      */
     Transient = 0x4,
 }
@@ -95,7 +102,7 @@ function decompressInterval(interval: CompressedSerializedInterval, label?: stri
         end: interval[1],
         sequenceNumber: interval[2],
         intervalType: interval[3],
-        properties: { ...interval[4], [reservedRangeLabelsKey]: label },
+        properties: { ...interval[4], [reservedRangeLabelsKey]: [label] },
     };
 }
 
@@ -187,11 +194,7 @@ export class Interval implements ISerializableInterval {
     }
 
     public serialize(client: Client): ISerializedInterval {
-        let seq = 0;
-        if (client) {
-            seq = client.getCurrentSeq();
-        }
-
+        const seq = client?.getCurrentSeq() ?? 0;
         const serializedInterval: ISerializedInterval = {
             end: this.end,
             intervalType: 0,
@@ -295,8 +298,9 @@ export class SequenceInterval implements ISerializableInterval {
     public propertyManager: PropertiesManager;
 
     constructor(
-        public start: LocalReference,
-        public end: LocalReference,
+        private readonly client: Client,
+        public start: LocalReferencePosition,
+        public end: LocalReferencePosition,
         public intervalType: IntervalType,
         props?: PropertySet,
     ) {
@@ -311,8 +315,8 @@ export class SequenceInterval implements ISerializableInterval {
     private callbacks?: Record<"beforePositionChange" | "afterPositionChange", () => void>;
 
     /**
-     * @internal
      * Subscribes to position change events on this interval if there are no current listeners.
+     * @internal
      */
     public addPositionChangeListeners(beforePositionChange: () => void, afterPositionChange: () => void): void {
         if (this.callbacks === undefined) {
@@ -329,8 +333,8 @@ export class SequenceInterval implements ISerializableInterval {
     }
 
     /**
-     * @internal
      * Removes the currently subscribed position change listeners.
+     * @internal
      */
     public removePositionChangeListeners(): void {
         if (this.callbacks) {
@@ -341,8 +345,8 @@ export class SequenceInterval implements ISerializableInterval {
     }
 
     public serialize(client: Client): ISerializedInterval {
-        const startPosition = this.start.toPosition();
-        const endPosition = this.end.toPosition();
+        const startPosition = client.localReferencePositionToPosition(this.start);
+        const endPosition = client.localReferencePositionToPosition(this.end);
         const serializedInterval: ISerializedInterval = {
             end: endPosition,
             intervalType: this.intervalType,
@@ -358,7 +362,7 @@ export class SequenceInterval implements ISerializableInterval {
     }
 
     public clone() {
-        return new SequenceInterval(this.start, this.end, this.intervalType, this.properties);
+        return new SequenceInterval(this.client, this.start, this.end, this.intervalType, this.properties);
     }
 
     public compare(b: SequenceInterval) {
@@ -384,16 +388,16 @@ export class SequenceInterval implements ISerializableInterval {
     }
 
     public compareStart(b: SequenceInterval) {
-        return this.start.compare(b.start);
+        return compareReferencePositions(this.start, b.start);
     }
 
     public compareEnd(b: SequenceInterval) {
-        return this.end.compare(b.end);
+        return compareReferencePositions(this.end, b.end);
     }
 
     public overlaps(b: SequenceInterval) {
-        const result = (this.start.compare(b.end) <= 0) &&
-            (this.end.compare(b.start) >= 0);
+        const result = (compareReferencePositions(this.start, b.end) <= 0) &&
+            (compareReferencePositions(this.end, b.start) >= 0);
         return result;
     }
 
@@ -406,8 +410,8 @@ export class SequenceInterval implements ISerializableInterval {
     }
 
     public union(b: SequenceInterval) {
-        return new SequenceInterval(this.start.min(b.start),
-            this.end.max(b.end), this.intervalType);
+        return new SequenceInterval(this.client, minReferencePosition(this.start, b.start),
+            maxReferencePosition(this.end, b.end), this.intervalType);
     }
 
     public addProperties(
@@ -421,12 +425,12 @@ export class SequenceInterval implements ISerializableInterval {
     }
 
     public overlapsPos(bstart: number, bend: number) {
-        const startPos = this.start.toPosition();
-        const endPos = this.start.toPosition();
+        const startPos = this.client.localReferencePositionToPosition(this.start);
+        const endPos = this.client.localReferencePositionToPosition(this.end);
         return (endPos > bstart) && (startPos < bend);
     }
 
-    public modify(label: string, start: number, end: number, op?: ISequencedDocumentMessage) {
+    public modify(label: string, start: number, end: number, op?: ISequencedDocumentMessage, localSeq?: number) {
         const getRefType = (baseType: ReferenceType): ReferenceType => {
             let refType = baseType;
             if (op === undefined) {
@@ -438,20 +442,21 @@ export class SequenceInterval implements ISerializableInterval {
 
         let startRef = this.start;
         if (start !== undefined) {
-            startRef = createPositionReference(this.start.getClient(), start, getRefType(this.start.refType), op);
+            startRef = createPositionReference(
+                this.client, start, getRefType(this.start.refType), op, undefined, localSeq,
+            );
             startRef.addProperties(this.start.properties);
         }
 
         let endRef = this.end;
         if (end !== undefined) {
-            endRef = createPositionReference(this.end.getClient(), end, getRefType(this.end.refType), op);
+            endRef = createPositionReference(
+                this.client, end, getRefType(this.end.refType), op, undefined, localSeq,
+            );
             endRef.addProperties(this.end.properties);
         }
 
-        startRef.pairedRef = endRef;
-        endRef.pairedRef = startRef;
-
-        const newInterval = new SequenceInterval(startRef, endRef, this.intervalType);
+        const newInterval = new SequenceInterval(this.client, startRef, endRef, this.intervalType);
         if (this.properties) {
             newInterval.initializeProperties();
             this.propertyManager.copyTo(this.properties, newInterval.properties, newInterval.propertyManager);
@@ -473,16 +478,18 @@ function createPositionReferenceFromSegoff(
     client: Client,
     segoff: { segment: ISegment | undefined; offset: number | undefined; },
     refType: ReferenceType,
-    op?: ISequencedDocumentMessage): LocalReference {
+    op?: ISequencedDocumentMessage): LocalReferencePosition {
     if (segoff.segment) {
         const ref = client.createLocalReferencePosition(segoff.segment, segoff.offset, refType, undefined);
-        return ref as LocalReference;
-    } else {
-        if (!op && !refTypeIncludesFlag(refType, ReferenceType.Transient)) {
-            throw new UsageError("Non-transient references need segment");
-        }
-        return new LocalReference(client, undefined, 0, refType);
+        return ref;
+    }
+
+    if (!op && !refTypeIncludesFlag(refType, ReferenceType.Transient)) {
+        // reference to segment that dne locally
+        throw new UsageError("Non-transient references need segment");
     }
+
+    return createDetachedLocalReferencePosition(refType);
 }
 
 function createPositionReference(
@@ -490,7 +497,9 @@ function createPositionReference(
     pos: number,
     refType: ReferenceType,
     op?: ISequencedDocumentMessage,
-    fromSnapshot?: boolean): LocalReference {
+    fromSnapshot?: boolean,
+    localSeq?: number,
+): LocalReferencePosition {
     let segoff;
     if (op) {
         assert((refType & ReferenceType.SlideOnRemove) !== 0, 0x2f5 /* op create references must be SlideOnRemove */);
@@ -499,7 +508,7 @@ function createPositionReference(
     } else {
         assert((refType & ReferenceType.SlideOnRemove) === 0 || fromSnapshot,
             0x2f6 /* SlideOnRemove references must be op created */);
-        segoff = client.getContainingSegment(pos);
+        segoff = client.getContainingSegment(pos, undefined, localSeq);
     }
     return createPositionReferenceFromSegoff(client, segoff, refType, op);
 }
@@ -536,15 +545,13 @@ function createSequenceInterval(
 
     const startLref = createPositionReference(client, start, beginRefType, op, fromSnapshot);
     const endLref = createPositionReference(client, end, endRefType, op, fromSnapshot);
-    startLref.pairedRef = endLref;
-    endLref.pairedRef = startLref;
     const rangeProp = {
         [reservedRangeLabelsKey]: [label],
     };
     startLref.addProperties(rangeProp);
     endLref.addProperties(rangeProp);
 
-    const ival = new SequenceInterval(startLref, endLref, intervalType, rangeProp);
+    const ival = new SequenceInterval(client, startLref, endLref, intervalType, rangeProp);
     return ival;
 }
 
@@ -793,18 +800,23 @@ export class LocalIntervalCollection<TInterval extends ISerializableInterval> {
             if (!interval.properties) {
                 interval.properties = createMap<any>();
             }
+
             if (props) {
                 interval.addProperties(props);
             }
-            if (interval.properties[reservedIntervalIdKey] === undefined) {
-                // Create a new ID.
-                interval.properties[reservedIntervalIdKey] = uuid();
-            }
+            interval.properties[reservedIntervalIdKey] ??= uuid();
             this.add(interval);
         }
         return interval;
     }
 
+    private linkEndpointsToInterval(interval: TInterval): void {
+        if (interval instanceof SequenceInterval) {
+            interval.start.addProperties({ interval });
+            interval.end.addProperties({ interval });
+        }
+    }
+
     private addIntervalToIndex(interval: TInterval) {
         const id = interval.getIntervalId();
         assert(id !== undefined, 0x2c0 /* "ID must be created before adding interval to collection" */);
@@ -820,6 +832,7 @@ export class LocalIntervalCollection<TInterval extends ISerializableInterval> {
     }
 
     public add(interval: TInterval) {
+        this.linkEndpointsToInterval(interval);
         this.addIntervalToIndex(interval);
         this.addIntervalListeners(interval);
     }
@@ -828,8 +841,14 @@ export class LocalIntervalCollection<TInterval extends ISerializableInterval> {
         return this.intervalIdMap.get(id);
     }
 
-    public changeInterval(interval: TInterval, start: number, end: number, op?: ISequencedDocumentMessage) {
-        const newInterval = interval.modify(this.label, start, end, op) as TInterval | undefined;
+    public changeInterval(
+        interval: TInterval,
+        start: number,
+        end: number,
+        op?: ISequencedDocumentMessage,
+        localSeq?: number,
+    ) {
+        const newInterval = interval.modify(this.label, start, end, op, localSeq) as TInterval | undefined;
         if (newInterval) {
             this.removeExistingInterval(interval);
             this.add(newInterval);
@@ -867,7 +886,8 @@ export class LocalIntervalCollection<TInterval extends ISerializableInterval> {
     }
 }
 
-const compareSequenceIntervalEnds = (a: SequenceInterval, b: SequenceInterval): number => a.end.compare(b.end);
+const compareSequenceIntervalEnds = (a: SequenceInterval, b: SequenceInterval): number =>
+    compareReferencePositions(a.end, b.end);
 
 class SequenceIntervalCollectionFactory
     implements IValueFactory<IntervalCollection<SequenceInterval>> {
@@ -979,6 +999,11 @@ function makeOpsMap<T extends ISerializableInterval>(): Map<string, IValueOperat
             "add",
             {
                 process: (collection, params, local, op) => {
+                    // if params is undefined, the interval was deleted during
+                    // rebasing
+                    if (!params) {
+                        return;
+                    }
                     collection.ackAdd(params, local, op);
                 },
                 rebase,
@@ -1000,6 +1025,11 @@ function makeOpsMap<T extends ISerializableInterval>(): Map<string, IValueOperat
             "change",
             {
                 process: (collection, params, local, op) => {
+                    // if params is undefined, the interval was deleted during
+                    // rebasing
+                    if (!params) {
+                        return;
+                    }
                     collection.ackChange(params, local, op);
                 },
                 rebase,
@@ -1062,7 +1092,7 @@ export class IntervalCollection<TInterval extends ISerializableInterval>
     private savedSerializedIntervals?: ISerializedInterval[];
     private localCollection: LocalIntervalCollection<TInterval>;
     private onDeserialize: DeserializeCallback | undefined;
-    private client: Client;
+    private client: Client | undefined;
     private readonly pendingChangesStart: Map<string, ISerializedInterval[]> = new Map<string, ISerializedInterval[]>();
     private readonly pendingChangesEnd: Map<string, ISerializedInterval[]> = new Map<string, ISerializedInterval[]>();
 
@@ -1079,12 +1109,9 @@ export class IntervalCollection<TInterval extends ISerializableInterval>
     ) {
         super();
 
-        if (Array.isArray(serializedIntervals)) {
-            this.savedSerializedIntervals = serializedIntervals;
-        } else {
-            this.savedSerializedIntervals =
-                serializedIntervals.intervals.map((i) => decompressInterval(i, serializedIntervals.label));
-        }
+        this.savedSerializedIntervals = Array.isArray(serializedIntervals)
+            ? serializedIntervals
+            : serializedIntervals.intervals.map((i) => decompressInterval(i, serializedIntervals.label));
     }
 
     public attachGraph(client: Client, label: string) {
@@ -1128,7 +1155,11 @@ export class IntervalCollection<TInterval extends ISerializableInterval>
      * Gets the next local sequence number, modifying this client's collab window in doing so.
      */
     private getNextLocalSeq(): number {
-        return ++this.client.getCollabWindow().localSeq;
+        if (this.client) {
+            return ++this.client.getCollabWindow().localSeq;
+        }
+
+        return 0;
     }
 
     public getIntervalById(id: string) {
@@ -1330,11 +1361,6 @@ export class IntervalCollection<TInterval extends ISerializableInterval>
         return entries && entries.length !== 0;
     }
 
-    /** @deprecated - use ackChange */
-    public changeInterval(serializedInterval: ISerializedInterval, local: boolean, op: ISequencedDocumentMessage) {
-        return this.ackChange(serializedInterval, local, op);
-    }
-
     /** @internal */
     public ackChange(serializedInterval: ISerializedInterval, local: boolean, op: ISequencedDocumentMessage) {
         if (!this.attached) {
@@ -1415,12 +1441,22 @@ export class IntervalCollection<TInterval extends ISerializableInterval>
         });
     }
 
-    /** @internal */
+    /**
+     * Returns new interval after rebasing. If undefined, the interval was
+     * deleted as a result of rebasing. This can occur if the interval applies
+     * to a range that no longer exists, and the interval was unable to slide.
+     *
+     * @internal
+     */
     public rebaseLocalInterval(
         opName: string,
         serializedInterval: ISerializedInterval,
         localSeq: number,
-    ) {
+    ): ISerializedInterval | undefined {
+        if (!this.client) {
+            // If there's no associated mergeTree client, the originally submitted op is still correct.
+            return serializedInterval;
+        }
         if (!this.attached) {
             throw new LoggingError("attachSequence must be called");
         }
@@ -1432,6 +1468,8 @@ export class IntervalCollection<TInterval extends ISerializableInterval>
             this.client.rebasePosition(end, sequenceNumber, localSeq);
 
         const intervalId = properties?.[reservedIntervalIdKey];
+        const localInterval = this.localCollection.getIntervalById(intervalId);
+
         const rebased: ISerializedInterval = {
             start: startRebased,
             end: endRebased,
@@ -1439,22 +1477,56 @@ export class IntervalCollection<TInterval extends ISerializableInterval>
             sequenceNumber: this.client?.getCurrentSeq() ?? 0,
             properties,
         };
+
         if (opName === "change" && (this.hasPendingChangeStart(intervalId) || this.hasPendingChangeEnd(intervalId))) {
             this.removePendingChange(serializedInterval);
             this.addPendingChange(intervalId, rebased);
         }
+
+        // if the interval slid off the string, rebase the op to be a noop and
+        // delete the interval
+        if (startRebased === DetachedReferencePosition || endRebased === DetachedReferencePosition) {
+            if (localInterval) {
+                this.localCollection.removeExistingInterval(localInterval);
+            }
+            return undefined;
+        }
+
+        if (!localInterval) {
+            return rebased;
+        }
+
+        // we know we must be using `SequenceInterval` because `this.client` exists
+        assert(
+            localInterval instanceof SequenceInterval,
+            0x3a0 /* localInterval must be `SequenceInterval` when used with client */,
+        );
+
+        const startSegment = this.getSlideToSegment(localInterval.start);
+        const endSegment = this.getSlideToSegment(localInterval.end);
+
+        // we need to slide because the reference has been removed
+        if (startSegment || endSegment) {
+            const newStart =
+                startSegment && this.client.getPosition(startSegment.segment, localSeq) + startSegment.offset;
+            const newEnd =
+                endSegment && this.client.getPosition(endSegment.segment, localSeq) + endSegment.offset;
+
+            this.localCollection.changeInterval(localInterval, newStart, newEnd, undefined, localSeq);
+        }
+
         return rebased;
     }
 
-    private getSlideToSegment(lref: LocalReference) {
-        const segoff = { segment: lref.segment, offset: lref.offset };
+    private getSlideToSegment(lref: LocalReferencePosition) {
+        const segoff = { segment: lref.getSegment(), offset: lref.getOffset() };
         const newSegoff = this.client.getSlideToSegment(segoff);
         const value: { segment: ISegment | undefined; offset: number | undefined; } | undefined
             = (segoff.segment === newSegoff.segment && segoff.offset === newSegoff.offset) ? undefined : newSegoff;
         return value;
     }
 
-    private setSlideOnRemove(lref: LocalReference) {
+    private setSlideOnRemove(lref: LocalReferencePosition) {
         let refType = lref.refType;
         refType = refType & ~ReferenceType.StayOnRemove;
         refType = refType | ReferenceType.SlideOnRemove;
@@ -1462,7 +1534,7 @@ export class IntervalCollection<TInterval extends ISerializableInterval>
     }
 
     private ackInterval(interval: TInterval, op: ISequencedDocumentMessage) {
-        // in current usage, interval is always a SequenceInterval
+        // Only SequenceIntervals need potential sliding
         if (!(interval instanceof SequenceInterval)) {
             return;
         }
@@ -1493,7 +1565,7 @@ export class IntervalCollection<TInterval extends ISerializableInterval>
         if (needsStartUpdate || needsEndUpdate) {
             // In this case, where we change the start or end of an interval,
             // it is necessary to remove and re-add the interval listeners.
-            // This ensures that the correct listeners are added to the ReferencePosition.
+            // This ensures that the correct listeners are added to the LocalReferencePosition.
             this.localCollection.removeExistingInterval(interval);
 
             if (needsStartUpdate) {
@@ -1516,14 +1588,6 @@ export class IntervalCollection<TInterval extends ISerializableInterval>
         }
     }
 
-    /** @deprecated - use ackAdd */
-    public addInternal(
-        serializedInterval: ISerializedInterval,
-        local: boolean,
-        op: ISequencedDocumentMessage) {
-        return this.ackAdd(serializedInterval, local, op);
-    }
-
     /** @internal */
     public ackAdd(
         serializedInterval: ISerializedInterval,
@@ -1562,14 +1626,6 @@ export class IntervalCollection<TInterval extends ISerializableInterval>
         return interval;
     }
 
-    /** @deprecated - use ackDelete */
-    public deleteInterval(
-        serializedInterval: ISerializedInterval,
-        local: boolean,
-        op: ISequencedDocumentMessage): void {
-        return this.ackDelete(serializedInterval, local, op);
-    }
-
     /** @internal */
     public ackDelete(
         serializedInterval: ISerializedInterval,
@@ -1673,3 +1729,31 @@ export class IntervalCollection<TInterval extends ISerializableInterval>
         return this.localCollection.nextInterval(pos);
     }
 }
+
+/**
+ * Information that identifies an interval within a `Sequence`.
+ */
+export interface IntervalLocator {
+    /**
+     * Label for the collection the interval is a part of
+     */
+    label: string;
+    /**
+     * Interval within that collection
+     */
+    interval: SequenceInterval;
+}
+
+/**
+ * Returns an object that can be used to find the interval a given LocalReferencePosition belongs to.
+ * @returns undefined if the reference position is not the endpoint of any interval (e.g. it was created
+ * on the merge tree directly by app code), otherwise an {@link IntervalLocator} for the interval this
+ * endpoint is a part of.
+ */
+export function intervalLocatorFromEndpoint(potentialEndpoint: LocalReferencePosition): IntervalLocator | undefined {
+    const {
+        interval,
+        [reservedRangeLabelsKey]: collectionNameArray,
+    } = potentialEndpoint.properties ?? {};
+    return (interval && collectionNameArray?.length === 1) ? { label: collectionNameArray[0], interval } : undefined;
+}

package/src/packageVersion.ts

@@ -6,4 +6,4 @@
  */
 
 export const pkgName = "@fluidframework/sequence";
-export const pkgVersion = "1.2.7";
+export const pkgVersion = "2.0.0-dev.1.3.0.96595";

package/src/sequence.ts

@@ -29,7 +29,6 @@ import {
     IRelativePosition,
     ISegment,
     ISegmentAction,
-    LocalReference,
     LocalReferencePosition,
     matchProperties,
     MergeTreeDeltaType,
@@ -67,7 +66,7 @@ const contentPath = "content";
 /**
  * Events emitted in response to changes to the sequence data.
  *
- *  @remarks
+ * @remarks
  *
  * The following is the list of events emitted.
  *
@@ -298,20 +297,6 @@ export abstract class SharedSegmentSequence<T extends ISegment>
         return this.client.getRangeExtentsOfPosition(pos);
     }
 
-    /**
-     * @deprecated - use createLocalReferencePosition
-     */
-    public createPositionReference(
-        segment: T,
-        offset: number,
-        refType: ReferenceType): LocalReference {
-        const lref = new LocalReference(this.client, segment, offset, refType);
-        if (refType !== ReferenceType.Transient) {
-            this.addLocalReference(lref);
-        }
-        return lref;
-    }
-
     public createLocalReferencePosition(
         segment: T,
         offset: number,
@@ -324,13 +309,6 @@ export abstract class SharedSegmentSequence<T extends ISegment>
             properties);
     }
 
-    /**
-     * @deprecated - use localReferencePositionToPosition
-     */
-    public localRefToPos(localRef: LocalReference) {
-        return this.client.localReferencePositionToPosition(localRef);
-    }
-
     public localReferencePositionToPosition(lref: ReferencePosition): number {
         return this.client.localReferencePositionToPosition(lref);
     }
@@ -377,20 +355,6 @@ export abstract class SharedSegmentSequence<T extends ISegment>
         }
     }
 
-    /**
-     * @deprecated - use createLocalReferencePosition
-     */
-    public addLocalReference(lref: LocalReference) {
-        return this.client.addLocalReference(lref);
-    }
-
-    /**
-     * @deprecated - use removeLocalReferencePosition
-     */
-    public removeLocalReference(lref: LocalReference) {
-        return this.client.removeLocalReferencePosition(lref);
-    }
-
     public removeLocalReferencePosition(lref: LocalReferencePosition) {
         return this.client.removeLocalReferencePosition(lref);
     }
@@ -424,6 +388,10 @@ export abstract class SharedSegmentSequence<T extends ISegment>
         return this.client.walkSegments<TClientData>(handler, start, end, accum, splitRange);
     }
 
+    /**
+     * @deprecated  for internal use only. public export will be removed.
+     * @internal
+     */
     public getStackContext(startPos: number, rangeLabels: string[]): RangeStackMap {
         return this.client.getStackContext(startPos, rangeLabels);
     }
@@ -440,8 +408,8 @@ export abstract class SharedSegmentSequence<T extends ISegment>
     }
 
     /**
-     * @deprecated - IntervalCollections are created on a first-write wins basis, and concurrent creates
-     * are supported. Use `getIntervalCollection` instead.
+     * @deprecated `IntervalCollection`s are created on a first-write wins basis, and concurrent creates
+     * are supported. Use {@link SharedSegmentSequence.getIntervalCollection} instead.
      */
     public async waitIntervalCollection(
         label: string,
@@ -454,12 +422,15 @@ export abstract class SharedSegmentSequence<T extends ISegment>
     }
 
     /**
-     * @returns an iterable object that enumerates the IntervalCollection labels
-     * Usage:
+     * @returns An iterable object that enumerates the IntervalCollection labels.
+     *
+     * @example
+     * ```typescript
      * const iter = this.getIntervalCollectionKeys();
      * for (key of iter)
      *     const collection = this.getIntervalCollection(key);
      *     ...
+     * ```
     */
     public getIntervalCollectionLabels(): IterableIterator<string> {
         return this.intervalCollections.keys();