Adds documentation for PathRef (#4740)

docs/api/locations/README.md

@@ -8,6 +8,7 @@ type Location = Path | Point | Range
 
 - [Location](./location.md)
 - [Path](./path.md)
+- [PathRef](./path-ref.md)
 - [Point](./point.md)
 - [PointEntry](./pointe-entry.md)
 - [Range](./range.md)

docs/api/locations/path-ref.md

@@ -0,0 +1,24 @@
+# PathRef API
+
+`PathRef` objects keep a specific path in a document synced over time as new operations are applied to the editor. You can access their property `current` at any time for the up-to-date `Path` value.
+When you no longer need to track this location, call `unref()` to free the resources.
+
+```typescript
+interface PathRef {
+  current: Path | null
+  affinity: 'forward' | 'backward' | null
+  unref(): Path | null
+}
+```
+
+- [Static methods](path-ref.md#static-methods)
+  - [Transform methods](path-ref.md#trasnform-methods)
+
+## Static methods
+
+### Transform methods
+
+#### `PathRef.transform(ref: PathRef, op: Operation)`
+
+Transform the path refs current value by an `op`.
+The editor calls this as needed, so normally you won't need to.

docs/api/locations/point-ref.md

@@ -1,6 +1,7 @@
 # PointRef API
 
 `PointRef` objects keep a specific point in a document synced over time as new operations are applied to the editor. You can access their property `current` at any time for the up-to-date `Point` value.
+When you no longer need to track this location, call `unref()` to free the resources.
 
 ```typescript
 interface PointRef {
@@ -28,4 +29,4 @@ It also returns the current value.
 #### `PointRef.transform(ref: PointRef, op: Operation)`
 
 Transform the point refs current value by an `op`.
-Rarely needed, as the PointRef is updated when the editor is updated.
+The editor calls this as needed, so normally you won't need to.

docs/api/locations/range-ref.md

@@ -1,6 +1,7 @@
 # RangeRef API
 
 `RangeRef` objects keep a specific range in a document synced over time as new operations are applied to the editor. You can access their property `current` at any time for the up-to-date `Range` value.
+When you no longer need to track this location, call `unref()` to free the resources.
 
 ```typescript
 interface RangeRef {
@@ -38,5 +39,5 @@ It also returns the current value.
 
 #### `RangeRef.transform(ref: RangeRef, op: Operation)`
 
-Transform the range refs current value by an `op`.  
-Rarely needed, as the RangeRef is updated when the editor is updated.
+Transform the range refs current value by an `op`.
+The editor calls this as needed, so normally you won't need to.