bookmarks.onMoved indexing clarification (mdn#18786)

* bookmarks.onMoved indexing clarification * Updated following feedback * Update for feedback
teoli2003 · Aug 18, 2022 · 5c5bb88 · 5c5bb88
1 parent ae1f7f8
commit 5c5bb88
Show file tree

Hide file tree

Showing 4 changed files with 8 additions and 1 deletion.
diff --git a/files/en-us/mozilla/add-ons/webextensions/api/bookmarks/bookmarktreenode/index.md b/files/en-us/mozilla/add-ons/webextensions/api/bookmarks/bookmarktreenode/index.md
@@ -31,6 +31,7 @@ An {{jsxref("object")}} with the following properties:
  - : A {{jsxref("string")}} which uniquely identifies the node. Each ID is unique within the user's profile and remains unchanged across browser restarts.
 - `index` {{optional_inline}}
  - : A number which represents the zero-based position of this node within its parent folder, where zero represents the first entry.
+ > **Note:** If you create or move multiple bookmarks, because the {{WebExtAPIRef("bookmarks.create()")}} and {{WebExtAPIRef("bookmarks.move()")}} methods are asynchronous, the requests may get processed in any order. Consequently, the value of each bookmark's index may change or be unknown until all the requests are completed. If the index associated with a bookmark matters to your extension, then – when creating or moving multiple bookmarks – the extension should wait for each `bookmarks.create` or `bookmarks.move` call to complete before creating or moving the next bookmark. Waiting ensures that the index associated with each bookmark is not affected by a create or move call executing concurrently while the original call is in progress.
 - `parentId` {{optional_inline}}
  - : A {{jsxref("string")}} which specifies the ID of the parent folder. This property is not present in the root node.
 - `title`

diff --git a/files/en-us/mozilla/add-ons/webextensions/api/bookmarks/create/index.md b/files/en-us/mozilla/add-ons/webextensions/api/bookmarks/create/index.md
@@ -38,6 +38,8 @@ let createBookmark = browser.bookmarks.create(
 
 A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that will be fulfilled with a {{WebExtAPIRef('bookmarks.BookmarkTreeNode', 'BookmarkTreeNode')}} that describes the new bookmark node.
 
+> **Note:** If you create multiple bookmarks, because this API is asynchronous, the create calls may get processed in any order. Consequently, the value of each bookmark's index returned in {{WebExtAPIRef('bookmarks.BookmarkTreeNode', 'BookmarkTreeNode')}} may change or be unknown until all the create calls are completed. If the index associated with a bookmark matters to your extension, then – when creating multiple bookmarks – the extension should wait for each `bookmarks.create`call to complete before creating the next bookmark. Waiting ensures that the index associated with each bookmark is not affected by a create call executing concurrently while the original call is in progress.
+
 ## Examples
 
 This example creates a bookmark for this page, placing it in the default folder ("Other Bookmarks" in Firefox and Chrome).

diff --git a/files/en-us/mozilla/add-ons/webextensions/api/bookmarks/move/index.md b/files/en-us/mozilla/add-ons/webextensions/api/bookmarks/move/index.md
@@ -49,6 +49,8 @@ A [`Promise`](/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise) that
 
 If the node corresponding to the `id` parameter can't be found, the promise is rejected with an error message.
 
+> **Note:** If you move multiple bookmarks, because this API is asynchronous, the move calls may get processed in any order. Consequently, the value of each bookmark's index returned in {{WebExtAPIRef('bookmarks.BookmarkTreeNode', 'BookmarkTreeNode')}} may change or be unknown until all the move calls are completed. If the index associated with a bookmark matters to your extension, then – when moving multiple bookmarks – the extension should wait for each `bookmarks.move` call to complete before moving the next bookmark. Waiting ensures that the index associated with each bookmark is not affected by a move call executing concurrently while the original call is in progress.
+
 ## Examples
 
 This example moves a bookmark so that it's the first bookmark in its current folder.

diff --git a/files/en-us/mozilla/add-ons/webextensions/api/bookmarks/onmoved/index.md b/files/en-us/mozilla/add-ons/webextensions/api/bookmarks/onmoved/index.md
@@ -15,7 +15,9 @@ browser-compat: webextensions.api.bookmarks.onMoved
 ---
 {{AddonSidebar()}}
 
-Fired when a bookmark or folder is moved to a different parent folder and/or position within a folder.
+Fired when a bookmark or folder is moved to a different parent folder or position within a folder.
+
+> **Note:** If you're moving multiple bookmarks, because this API is asynchronous, the move calls may get processed in any order. Consequently, the value of each bookmark's index may change or be unknown until all the move calls are completed. If the index associated with a bookmark matters to your extension, then – when moving multiple bookmarks – the extension should wait for each `bookmarks.move` call to complete before moving the next bookmark. Waiting ensures that the index associated with each bookmark is not affected by a move call executing concurrently while the original call is in progress.
 
 ## Syntax