1 files changed, 94 insertions, 0 deletions
diff --git a/toolkit/components/extensions/docs/generate_webidl_from_jsonschema.rst b/toolkit/components/extensions/docs/generate_webidl_from_jsonschema.rst
new file mode 100644
index 0000000000..f4514bfa25
--- /dev/null
+++ b/toolkit/components/extensions/docs/generate_webidl_from_jsonschema.rst
@@ -0,0 +1,94 @@
+Generating WebIDL definitions from WebExtensions API JSONSchema
+===============================================================
+
+In ``toolkit/components/extensions/webidl-api``, a python script named ``GenerateWebIDLBindings.py``
+helps to generation of the WebIDL definitions for the WebExtensions API namespaces based on the existing
+JSONSchema data.
+
+.. figure:: generate_webidl_from_jsonschema_dataflow.drawio.svg
+   :alt: Diagram of the GenerateWebIDLBindings.py script data flow
+
+..
+   This svg diagram has been created using https://app.diagrams.net,
+   the svg file also includes the source in the drawio format and so
+   it can be edited more easily by loading it back into app.diagrams.net
+   and then re-export from there (and include the updated drawio format
+   content into the exported svg file).
+
+Example: how to execute GenerateWebIDLBindings.py
+-------------------------------------------------
+
+As an example, the following shell command generates (or regenerates if one exists) the webidl bindings
+for the `runtime` API namespace:
+
+.. code-block:: bash
+
+    $ export SCRIPT_DIR="toolkit/components/extensions/webidl-api"
+    $ mach python $SCRIPT_DIR/GenerateWebIDLBindings.py -- runtime
+
+this command will generates a `.webdil` file named `dom/webidl/ExtensionRuntime.webidl`.
+
+.. warning::
+    This python script uses some python libraries part of mozilla-central ``mach`` command
+    and so it has to be executed using ``mach python`` and any command line options that has
+    to the passed to the ``GenerateWebIDLBindings.py`` script should be passed after the ``--``
+    one that ends ``mach python`` own command line options.
+
+* If a webidl file with the same name already exist, the python script will ask confirmation and
+  offer to print a diff of the changes (or just continue without changing the existing webidl file
+  if the content is exactly the same):
+
+.. code-block:: console
+
+    $ mach python $SCRIPT_DIR/GenerateWebIDLBindings.py -- runtime
+
+    Generating webidl definition for 'runtime' => dom/webidl/ExtensionRuntime.webidl
+    Found existing dom/webidl/ExtensionRuntime.webidl.
+
+    (Run again with --overwrite-existing to allow overwriting it automatically)
+
+    Overwrite dom/webidl/ExtensionRuntime.webidl? (Yes/No/Diff)
+    D
+    --- ExtensionRuntime.webidl--existing
+    +++ ExtensionRuntime.webidl--updated
+    @@ -24,6 +24,9 @@
+     [Exposed=(ServiceWorker), LegacyNoInterfaceObject]
+     interface ExtensionRuntime {
+       // API methods.
+    +
+    +  [Throws, WebExtensionStub="Async"]
+    +  any myNewMethod(boolean aBoolParam, optional Function callback);
+
+       [Throws, WebExtensionStub="Async"]
+       any openOptionsPage(optional Function callback);
+
+
+    Overwrite dom/webidl/ExtensionRuntime.webidl? (Yes/No/Diff)
+
+* By convention each WebExtensions API WebIDL binding is expected to be paired with C++ files
+  named ``ExtensionMyNamespace.h`` and ``ExtensionMyNamespace.cpp`` and located in
+  ``toolkit/components/extensions/webidl-api``:
+
+  * if no files with the expected names is found the python script will generate an initial
+    boilerplate files and will store them in the expected mozilla-central directory.
+  * The Firefox developers are responsible to fill this initial boilerplate as needed and
+    to apply the necessary changes (if any) when the webidl definitions are updated because
+    of changes to the WebExtensions APIs JSONSchema.
+
+``ExtensionWebIDL.conf`` config file
+------------------------------------
+
+TODO:
+
+* mention the role of the "webidl generation" script config file in handling
+  special cases (e.g. mapping types and method stubs)
+
+* notes on desktop-only APIs and API namespaces only partially available on Android
+
+
+``WebExtensionStub`` WebIDL extended attribute
+----------------------------------------------
+
+TODO:
+
+* mention the special webidl extended attribute used in the WebIDL definitions