onChanged callback object content clarification (#31227)

* onChanged callback object content clarification * Revert "onChanged callback object content clarification" This reverts commit 033a77c. * Revised change * Further clarification and bug information * Apply suggestions from review Co-authored-by: Joe Medley <[email protected]> * Apply suggestions from review Co-authored-by: Joe Medley <[email protected]> --------- Co-authored-by: Joe Medley <[email protected]>
mdn · Mar 4, 2024 · b9e1bf1 · b9e1bf1
1 parent 3201067
commit b9e1bf1
Show file tree

Hide file tree

Showing 2 changed files with 7 additions and 5 deletions.
diff --git a/files/en-us/mozilla/add-ons/webextensions/api/storage/onchanged/index.md b/files/en-us/mozilla/add-ons/webextensions/api/storage/onchanged/index.md
@@ -7,9 +7,9 @@ browser-compat: webextensions.api.storage.onChanged
 
 {{AddonSidebar}}
 
-Fired when {{WebExtAPIRef('storage.StorageArea.set','storageArea.set')}}, {{WebExtAPIRef('storage.StorageArea.remove','storageArea.remove')}}, or {{WebExtAPIRef('storage.StorageArea.clear','storageArea.clear')}} executes against a storage area.
+Fired when {{WebExtAPIRef('storage.StorageArea.set','storageArea.set')}}, {{WebExtAPIRef('storage.StorageArea.remove','storageArea.remove')}}, or {{WebExtAPIRef('storage.StorageArea.clear','storageArea.clear')}} executes against a storage area, returning details of only changed keys. A callback is called only when there are changes to the underlying data.
 
-When this event is triggered by {{WebExtAPIRef('storage.StorageArea.set','storageArea.set')}}, it's possible to receive a callback when there is no change to the underlying data. Also, the information returned includes all keys within the storage area {{WebExtAPIRef('storage.StorageArea.set','storageArea.set')}} ran against. The extension can determine the changes that occurred by examining the content of the `changes` argument received by the `onChanged` listeners.
+> **Note:** In Firefox, the information returned includes all keys within the storage area {{WebExtAPIRef('storage.StorageArea.set','storageArea.set')}} ran against whether they changed or not. Also, a callback may be invoked when there is no change to the underlying data. Details of the changed items are found by examining each returned key's {{WebExtAPIRef('storage.StorageChange')}} object. See [Firefox bug 1833153](https://bugzil.la/1833153).
 
 ## Syntax
 
@@ -37,7 +37,7 @@ Events have three functions:
   - : The function called when this event occurs. The function is passed these arguments:
 
     - `changes`
-      - : `object`. Object describing the change. This object contains properties for all the keys in the storage area included in the {{WebExtAPIRef('storage.StorageArea.set','storageArea.set')}} call, even if key values are unchanged. The name of each property is the name of each key. The value of each key is a {{WebExtAPIRef('storage.StorageChange')}} object describing the change to that item.
+      - : `object`. Object describing the change. The name of each property is the name of each key. The value of each key is a {{WebExtAPIRef('storage.StorageChange')}} object describing the change to that item.
     - `areaName`
       - : `string`. The name of the storage area (`"sync"`, `"local"`, or `"managed"`) to which the changes were made.
 

diff --git a/.../en-us/mozilla/add-ons/webextensions/api/storage/storagearea/onchanged/index.md b/.../en-us/mozilla/add-ons/webextensions/api/storage/storagearea/onchanged/index.md
@@ -7,7 +7,9 @@ browser-compat: webextensions.api.storage.StorageArea.onChanged
 
 {{AddonSidebar}}
 
-Fires when one or more items in a storage area change. Compared to {{WebExtAPIRef("storage.onChanged")}}, this event enables you to listen for changes in one of the storage areas: `local`, `managed`, `session`, and `sync`.
+Fires when one or more items in a storage area change, returning details for the keys that changed. Compared to {{WebExtAPIRef("storage.onChanged")}}, this event enables you to listen for changes in one of the storage areas: `local`, `managed`, `session`, and `sync`.
+
+> **Note:** In Firefox, the information returned includes all keys within the storage area. Also, the callback may be invoked when there is no change to the underlying data. Details of the changed items are found by examining each returned key's {{WebExtAPIRef('storage.StorageChange')}} object. See [Firefox bug 1833153](https://bugzil.la/1833153).
 
 ## Syntax
 
@@ -36,7 +38,7 @@ Events have three functions:
   - : The function called when this event occurs. The function is passed this argument:
 
     - `changes`
-      - : `object`. Object describing the change. This contains one property for each key that changed. The name of the property is the name of the key that changed, and its value is a {{WebExtAPIRef('storage.StorageChange')}} object describing the change to that item.
+      - : `object`. Object describing the change. This contains one property for each key that changed. The property name is the name of the key that changed, and its value is a {{WebExtAPIRef('storage.StorageChange')}} object describing the change to that item.
 
 ## Examples