From c90ec8e8371eee01e72729b1a5af70e1d8cddbb1 Mon Sep 17 00:00:00 2001
From: Doug Reeder <reeder.29@gmail.com>
Date: Wed, 22 Dec 2021 07:04:14 -0500
Subject: [PATCH] Adds documentation for PathRef (#4740)

---
 docs/api/locations/README.md    |  1 +
 docs/api/locations/path-ref.md  | 24 ++++++++++++++++++++++++
 docs/api/locations/point-ref.md |  3 ++-
 docs/api/locations/range-ref.md |  5 +++--
 site/examples/paste-html.tsx    |  2 +-
 5 files changed, 31 insertions(+), 4 deletions(-)
 create mode 100644 docs/api/locations/path-ref.md

diff --git a/docs/api/locations/README.md b/docs/api/locations/README.md
index 4ad932e9b..205ed7d32 100644
--- a/docs/api/locations/README.md
+++ b/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)
diff --git a/docs/api/locations/path-ref.md b/docs/api/locations/path-ref.md
new file mode 100644
index 000000000..f27bb5c29
--- /dev/null
+++ b/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.
diff --git a/docs/api/locations/point-ref.md b/docs/api/locations/point-ref.md
index 9134bff6d..2dd132bbe 100644
--- a/docs/api/locations/point-ref.md
+++ b/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.
diff --git a/docs/api/locations/range-ref.md b/docs/api/locations/range-ref.md
index 84e0d8ddf..f8bd1b8f8 100644
--- a/docs/api/locations/range-ref.md
+++ b/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.
diff --git a/site/examples/paste-html.tsx b/site/examples/paste-html.tsx
index 0d462c663..6f5f7366a 100644
--- a/site/examples/paste-html.tsx
+++ b/site/examples/paste-html.tsx
@@ -226,7 +226,7 @@ const initialValue: Descendant[] = [
       { text: "'text/plain'", code: true },
       {
         text:
-          " data. That's okay for some use cases, but sometimes you want users to be able to paste in content and have it maintaing its formatting. To do this, your editor needs to handle ",
+          " data. That's okay for some use cases, but sometimes you want users to be able to paste in content and have it maintain its formatting. To do this, your editor needs to handle ",
       },
       { text: "'text/html'", code: true },
       { text: ' data. ' },