diff --git a/docs/api/transforms.md b/docs/api/transforms.md
index 589a46160..11de3c4e7 100644
--- a/docs/api/transforms.md
+++ b/docs/api/transforms.md
@@ -106,7 +106,7 @@ Options: `{edge?: 'anchor' | 'focus' | 'start' | 'end'}`
 
 #### `Transforms.select(editor: Editor, target: Location)`
 
-Set the selection to a new value specified by `target`.
+Set the selection to a new value specified by `target`. When a selection already exists, this method is just a proxy for `setSelection` and will update the existing value.
 
 #### `Transforms.deselect(editor: Editor)`
 
@@ -126,7 +126,7 @@ Options: `{edge?: 'anchor' | 'focus' | 'start' | 'end'}`
 
 #### `Transforms.setSelection(editor: Editor, props: Partial<Range>)`
 
-Set new properties on the selection.
+Set new properties on an active selection. Since the value is a `Partial<Range>`, this method can only handle updates to an existing selection. If there is no active selection the operation will be void. Use `select` if you'd like to create a selection when there is none.
 
 ### Text transforms