Clarifies docs for RangeRef & PointRef; fixes TOC for Editor API (#4724)

docs/api/locations/point-ref.md

@@ -10,9 +10,17 @@ interface PointRef {
 }
 ```
 
+- [Instance methods](point-ref.md#instance-methods)
 - [Static methods](point-ref.md#static-methods)
   - [Transform methods](point-ref.md#trasnform-methods)
 
+## Instance methods
+
+#### `unRef() => Point`
+
+Call this when you no longer need to sync this point.
+It also returns the current value.
+
 ## Static methods
 
 ### Transform methods
@@ -20,3 +28,4 @@ interface PointRef {
 #### `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.

docs/api/locations/range-ref.md

@@ -10,13 +10,33 @@ interface RangeRef {
 }
 ```
 
+For example:
+
+```typescript
+const selectionRef = Editor.rangeRef(editor, editor.selection, {
+  affinity: 'inward',
+})
+// Allow the user to do stuff which might change the selection
+Transforms.unwrapNodes(editor)
+Transforms.select(editor, selectionRef.unRef())
+```
+
+- [Instance methods](range-ref.md#instance-methods)
 - [Static methods](range-ref.md#static-methods)
   - [Transform methods](range-ref.md#transform-methods)
 
+## Instance methods
+
+#### `unRef() => Range`
+
+Call this when you no longer need to sync this range.
+It also returns the current value.
+
 ## Static methods
 
 ### Transform methods
 
 #### `RangeRef.transform(ref: RangeRef, op: Operation)`
 
-Transform the range refs current value by an `op`.
+Transform the range refs current value by an `op`.  
+Rarely needed, as the RangeRef is updated when the editor is updated.