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,9 +10,28 @@ 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
@@ -20,3 +39,4 @@ interface RangeRef {
 #### `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.

docs/api/nodes/editor.md

@@ -37,6 +37,14 @@ interface Editor {
   - [Normalization methods](editor.md#normalization-methods)
 - [Instance methods](editor.md#instance-methods)
   - [Schema-specific methods to override](editor.md#schema-specific-instance-methods-to-override)
+  - [Element Type Methods](editor.md/#element-type-methods)
+  - [Normalize Method](editor.md/#normalize-method)
+  - [Callback Method](editor.md/#callback-method)
+  - [Mark Methods](editor.md/#mark-methods)
+  - [getFragment Method](editor.md/#getfragment-method)
+  - [Delete Methods](editor.md/#delete-methods)
+  - [Insert Methods](editor.md/#insert-methods)
+  - [Operation Handling Method](editor.md/#operation-handling-method)
 
 ## Instantiation methods
 
@@ -358,7 +366,9 @@ Options: `{force?: boolean}`
 
 Call a function, deferring normalization until after it completes.
 
-## Schema-specific instance methods to override
+## Instance Methods
+
+### Schema-specific instance methods to override
 
 Replace these methods to modify the original behavior of the editor when building [Plugins](../../concepts/08-plugins.md). When modifying behavior, call the original method when appropriate. For example, a plugin that marks image nodes as "void":
 

docs/general/faq.md

@@ -3,7 +3,6 @@
 A series of common questions people have about Slate:
 
 - [Why is content pasted as plain text?](faq.md#why-is-content-is-pasted-as-plaintext)
-- [What can a `Block` node have as its children?](faq.md#what-can-a-block-node-have-as-its-children)
 - [What browsers and devices does Slate support?](faq.md#what-browsers-and-devices-does-slate-support)
 
 ## Why is content pasted as plain text?