From 5adb8ededf90e12efd4307ee02019245d7e445f1 Mon Sep 17 00:00:00 2001
From: Deepak Kharah <42672761+Deepak-Kharah@users.noreply.github.com>
Date: Fri, 4 Apr 2025 10:40:34 +0530
Subject: [PATCH] doc: add missing APIs in the doc (#5835)

* doc: add missing APIs in the doc

* refactor: apply lint
---
 docs/api/locations/path-ref.md  |  7 +++++++
 docs/api/locations/path.md      |  4 ++++
 docs/api/locations/point-ref.md |  2 +-
 docs/api/locations/range-ref.md |  2 +-
 docs/api/nodes/editor.md        |  6 +++++-
 docs/api/nodes/node.md          | 33 +++++++++++++++++++++++++++++++++
 6 files changed, 51 insertions(+), 3 deletions(-)

diff --git a/docs/api/locations/path-ref.md b/docs/api/locations/path-ref.md
index 59c7e2353..78f51c28a 100644
--- a/docs/api/locations/path-ref.md
+++ b/docs/api/locations/path-ref.md
@@ -10,9 +10,16 @@ interface PathRef {
 }
 ```
 
+- [Instance methods](path-ref.md#instance-methods)
 - [Static methods](path-ref.md#static-methods)
   - [Transform methods](path-ref.md#trasnform-methods)
 
+## Instance methods
+
+#### `unref() => Path | null`
+
+Free the resources used by the PathRef. This should be called when you no longer need to track the path. Returns the final path value before being unrefed, or null if the path was already invalid.
+
 ## Static methods
 
 ### Transform methods
diff --git a/docs/api/locations/path.md b/docs/api/locations/path.md
index ee6a5b888..90d3ce38e 100644
--- a/docs/api/locations/path.md
+++ b/docs/api/locations/path.md
@@ -115,6 +115,10 @@ Check is a value implements the `Path` interface.
 
 Check if a path is a sibling of another.
 
+#### `Path.operationCanTransformPath(operation: Operation) => operation is InsertNodeOperation | RemoveNodeOperation | MergeNodeOperation | SplitNodeOperation | MoveNodeOperation`
+
+Returns whether this operation can affect paths or not.
+
 ### Transform method
 
 #### `Path.transform(path: Path, operation: Operation, options?) => Path | null`
diff --git a/docs/api/locations/point-ref.md b/docs/api/locations/point-ref.md
index b5b0c254e..c8c3507b7 100644
--- a/docs/api/locations/point-ref.md
+++ b/docs/api/locations/point-ref.md
@@ -16,7 +16,7 @@ interface PointRef {
 
 ## Instance methods
 
-#### `unRef() => Point`
+#### `unref() => Point | null`
 
 Call this when you no longer need to sync this point.
 It also returns the current value.
diff --git a/docs/api/locations/range-ref.md b/docs/api/locations/range-ref.md
index d6bab927b..b29d715b2 100644
--- a/docs/api/locations/range-ref.md
+++ b/docs/api/locations/range-ref.md
@@ -27,7 +27,7 @@ Transforms.select(editor, selectionRef.unref())
 
 ## Instance methods
 
-#### `unref() => Range`
+#### `unref() => Range | null`
 
 Call this when you no longer need to sync this range.
 It also returns the current value.
diff --git a/docs/api/nodes/editor.md b/docs/api/nodes/editor.md
index f48bcaa10..6ee8f4d40 100644
--- a/docs/api/nodes/editor.md
+++ b/docs/api/nodes/editor.md
@@ -246,6 +246,10 @@ Delete the content in the current selection.
 
 Insert a block break at the current selection.
 
+#### `Editor.insertSoftBreak(editor: Editor) => void`
+
+Insert a soft break at the current selection.
+
 #### `Editor.insertFragment(editor: Editor, fragment: Node[], options?) => void`
 
 Inserts a fragment at the specified location or (if not defined) the current selection or (if not defined) the end of the document.
@@ -444,7 +448,7 @@ Remove a custom property from the leaf text nodes within non-void nodes or void
 
 ### getFragment method
 
-#### `getFragment() => Descendant`
+#### `getFragment() => Descendant[]`
 
 Returns the fragment at the current selection. Used when cutting or copying, as an example, to get the fragment at the current selection.
 
diff --git a/docs/api/nodes/node.md b/docs/api/nodes/node.md
index 5fa617234..b9d1207b7 100644
--- a/docs/api/nodes/node.md
+++ b/docs/api/nodes/node.md
@@ -51,6 +51,26 @@ Return a generator of all the element nodes inside a root node. Each iteration w
 
 Options: `{from?: Path, to?: Path, reverse?: boolean, pass?: (node: NodeEntry => boolean)}`
 
+#### `Node.extractProps(node: Node) => NodeProps`
+
+Extract all properties from a Node except for its content-related fields (`children` for Element nodes and `text` for Text nodes).
+
+```typescript
+// For an Element node
+const element = {
+  type: 'paragraph',
+  align: 'center',
+  children: [{ text: 'Try it out for yourself!' }],
+}
+const props = Node.extractProps(element)
+// Returns: { type: 'paragraph', align: "center" }
+
+// For a Text node
+const text = { text: 'Hello', bold: true }
+const props = Node.extractProps(text)
+// Returns: { bold: true }
+```
+
 #### `Node.first(root: Node, path: Path) => NodeEntry`
 
 Get the first node entry in a root node from a `path`.
@@ -63,6 +83,19 @@ Get the sliced fragment represented by the `range`.
 
 Get the descendant node referred to by a specific `path`. If the path is an empty array, get the root node itself.
 
+#### `Node.getIf(root: Node, path: Path) => Node | undefined`
+
+Get a descendant node at a specific path, returning `undefined` if the node does not exist. This is a safer alternative to `Node.get()` as it won't throw an error if the path is invalid.
+
+```typescript
+const node = Node.getIf(root, [0, 1])
+if (node) {
+  // node exists at path [0, 1]
+} else {
+  // no node exists at path [0, 1]
+}
+```
+
 #### `Node.last(root: Node, path: Path) => NodeEntry`
 
 Get the last node entry in a root node at a specific `path`.