Update commands page (bug 1681153)

changes/beta87.rst

@@ -0,0 +1,9 @@
+=========================
+Changes in Thunderbird 87
+=========================
+
+commands
+========
+
+* The commands API now supports the internal shortcuts ``_execute_compose_action`` and ``_execute_message_display_action``.
+

commands.rst

@@ -20,6 +20,13 @@ Manifest file properties
 .. api-member::
    :name: [``commands``]
    :type: (object)
+
+   Object defining one or more commands as key-value pairs, the key being the name of the command and the value being a :ref:`commands.CommandsShortcut`. The key may also be one of the built-in special shortcuts ``_execute_browser_action``, ``_execute_compose_action`` or ``_execute_message_display_action``. Example: 
+
+   .. literalinclude:: includes/commands/manifest.json
+     :language: JSON
+
+   .
 
 .. rst-class:: api-permission-info
 
@@ -69,7 +76,7 @@ Update the details of an already defined command.
          :name: [``shortcut``]
          :type: (string)
 
-         An empty string to clear the shortcut, or a string matching the format of the `commands manifest.json key <https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/commands>`_  to set a new shortcut key. If the string does not match this format, the function throws an error.
+         An empty string to clear the shortcut, or a string matching the format defined by the `MDN page of the commands API <https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/commands#shortcut_values>`_  to set a new shortcut key. If the string does not match this format, the function throws an error.
 
 
 
@@ -171,3 +178,64 @@ Command
 
       The shortcut active for this command, or blank if not active.
 
+
+.. _commands.CommandsShortcut:
+
+CommandsShortcut
+----------------
+
+.. api-section-annotation-hack:: 
+
+.. api-header::
+   :label: object
+
+
+   .. api-member::
+      :name: [``description``]
+      :type: (string)
+
+
+   .. api-member::
+      :name: [``suggested_key``]
+      :type: (object)
+
+      .. api-member::
+         :name: [``default``]
+         :type: (:ref:`commands.KeyName`)
+
+         Default key combination.
+
+
+      .. api-member::
+         :name: [``linux``]
+         :type: (:ref:`commands.KeyName`)
+
+         Key combination on Linux.
+
+
+      .. api-member::
+         :name: [``mac``]
+         :type: (:ref:`commands.KeyName`)
+
+         Key combination on Mac.
+
+
+      .. api-member::
+         :name: [``windows``]
+         :type: (:ref:`commands.KeyName`)
+
+         Key combination on Windows.
+
+
+
+.. _commands.KeyName:
+
+KeyName
+-------
+
+.. api-section-annotation-hack:: 
+
+Definition of the shortcut, for example ``Alt+F5``. The string must match the shortcut format as defined by the `MDN page of the commands API <https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/commands#shortcut_values>`_.
+
+.. api-header::
+   :label: string

includes/commands/manifest.json

@@ -0,0 +1,15 @@
+"commands": {
+  "toggle-feature": {
+    "suggested_key": {
+      "default": "Ctrl+Shift+Y",
+      "linux": "Ctrl+Shift+U"
+    },
+    "description": "Send a 'toggle-feature' event"
+  },
+  "_execute_compose_action": {
+    "suggested_key": {
+      "default": "Alt+F5",
+    },
+    "description": "Open the compose action popup"
+  }
+}

overlay/commands.json

@@ -1,6 +1,63 @@
 [
+ {
+    "namespace": "manifest",
+    "types": [
+      {
+        "$extend": "WebExtensionManifest",
+        "properties": {
+          "commands": {
+            "description" : "Object defining one or more commands as key-value pairs, the key being the name of the command and the value being a :ref:`commands.CommandsShortcut`. The key may also be one of the built-in special shortcuts ``_execute_browser_action``, ``_execute_compose_action`` or ``_execute_message_display_action``. Example: <literalinclude>includes/commands/manifest.json<lang>JSON</lang></literalinclude>."
+          }
+        }
+      }
+    ]
+  },
   {
     "namespace": "commands",
+    "types": [
+     {
+        "id": "KeyName",
+        "type": "string",
+        "description": "Definition of the shortcut, for example ``Alt+F5``. The string must match the shortcut format as defined by the `MDN page of the commands API <https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/commands#shortcut_values>`_."
+      },
+      {
+        "id" : "CommandsShortcut",
+        "type": "object",
+        "properties" : {
+          "suggested_key": {
+            "type": "object",
+            "optional": true,
+            "properties": {
+              "default": {
+                "$ref": "KeyName",
+                "description": "Default key combination.",
+                "optional": true
+              },
+              "mac": {
+                "$ref": "KeyName",
+                "description": "Key combination on Mac.",
+                "optional": true
+              },
+              "linux": {
+                "$ref": "KeyName",
+                "description": "Key combination on Linux.",
+                "optional": true
+              },
+              "windows": {
+                "$ref": "KeyName",
+                "description": "Key combination on Windows.",
+                "optional": true
+              }
+            }
+          },
+          "description": {
+            "type": "string",
+            "preprocess": "localize",
+            "optional": true
+          }
+        }
+      }
+    ],
     "functions": [
       {
         "name": "update",
@@ -10,7 +67,7 @@
             "description": "",
             "properties": {
               "shortcut": {
-                "description": "An empty string to clear the shortcut, or a string matching the format of the `commands manifest.json key <https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/commands>`_  to set a new shortcut key. If the string does not match this format, the function throws an error."
+                "description": "An empty string to clear the shortcut, or a string matching the format defined by the `MDN page of the commands API <https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/commands#shortcut_values>`_  to set a new shortcut key. If the string does not match this format, the function throws an error."
               }
             }
           }