Clarify details returned in commands.Command

files/en-us/mozilla/add-ons/webextensions/api/commands/command/index.md

@@ -7,20 +7,22 @@ browser-compat: webextensions.api.commands.Command
 
 {{AddonSidebar}}
 
-Information about a command. This contains the information specified for the command in the [`commands` manifest.json key](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/commands).
+Information about the settings for the commands specified in the [`commands` manifest.json key](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/commands).
 
 An array of these objects is returned from {{WebExtAPIRef('commands.getAll()')}}.
 
 ## Type
 
-Values of this type are objects. They contain the following properties:
+A value of this type is an object containing these properties for the commands:
 
-- `name` {{optional_inline}}
-  - : `string`. Name of this command. This will be passed into the {{WebExtAPIRef('commands.onCommand')}} event listener.
+- `name`
+  - : `string`. Name of the command. This is passed into the {{WebExtAPIRef('commands.onCommand')}} event listener.
 - `description` {{optional_inline}}
-  - : `string`. Description of this command. This is primarily used to explain to the user what this command does.
+  - : `string`. Description of the command. This is used to explain to the user what this command does.
 - `shortcut` {{optional_inline}}
-  - : `string`. Key(s) used to execute this command, specified as a string like "Ctrl+Shift+Y".
+  - : `string`. Keys used to execute the command, specified as a string. See the [shortcut values][/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/commands#shortcut_values] section of the `commands` manifest key documentation for more details.
+
+`description` and `shortcut' reflect the values given in the `commands` manifest.json key unless they have been updated with {{WebExtAPIRef('commands.update()')}}` or, in the case of the shortcut, customized by the user.
 
 ## Browser compatibility
 

files/en-us/mozilla/add-ons/webextensions/api/commands/index.md

@@ -7,21 +7,21 @@ browser-compat: webextensions.api.commands
 
 {{AddonSidebar}}
 
-Listen for the user executing commands that you have registered using the [`commands` manifest.json key](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/commands).
+Listen for the user executing commands that your extension registered using the [`commands` manifest.json key](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/commands).
 
 ## Types
 
 - {{WebExtAPIRef("commands.Command")}}
-  - : Object representing a command. This contains the information specified for the command in the [`commands` manifest.json key](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/commands).
+  - : Object containing a command's settings.
 
 ## Functions
 
 - {{WebExtAPIRef("commands.getAll")}}
-  - : Gets all registered commands for this extension.
+  - : Gets all registered commands for the extension.
 - {{WebExtAPIRef("commands.reset")}}
-  - : Reset the given command's description and shortcut to the values given in the manifest key.
+  - : Reset a command's description and shortcut to the values given in the manifest key.
 - {{WebExtAPIRef("commands.update")}}
-  - : Change the description or shortcut for the given command.
+  - : Change the description or shortcut for a command.
 
 ## Events