Bug 1913427 - add documentation for XPCOMUtils into firefox-source-docs, r=xpcom-reviewers,frontend-codestyle-reviewers,nika,Standard8

Differential Revision: https://phabricator.services.mozilla.com/D219320

.eslintrc-rollouts.js

@@ -343,7 +343,7 @@ const rollouts = [
       "gfx/layers/apz/test/mochitest/apz_test_native_event_utils.js",
       "image/test/**",
       "intl/**",
-      "js/xpconnect/**",
+      "js/xpconnect/tests/**",
       "layout/**",
       "mobile/android/**",
       "mobile/shared/**",

docs/conf.py

@@ -63,6 +63,7 @@ js_source_path = [
     "../browser/components/migration/content",
     "../browser/components/uitour",
     "../browser/components/urlbar",
+    "../js/xpconnect/loader",
     "../remote/marionette",
     "../testing/mochitest/BrowserTestUtils",
     "../testing/mochitest/tests/SimpleTest/SimpleTest.js",

js/xpconnect/loader/ComponentUtils.sys.mjs

@@ -13,9 +13,12 @@ const nsIFactoryQI = ChromeUtils.generateQI(["nsIFactory"]);
 
 export var ComponentUtils = {
   /**
+   * DEPRECATED!
+   *
    * Generates a singleton nsIFactory implementation that can be used as
    * an argument to nsIComponentRegistrar.registerFactory.
-   * @param aServiceConstructor
+   *
+   * @param {Function} aServiceConstructor
    *        Constructor function of the component.
    */
   generateSingletonFactory(aServiceConstructor) {

js/xpconnect/loader/XPCOMUtils.sys.mjs

@@ -31,15 +31,25 @@ function redefine(object, prop, value) {
   return value;
 }
 
+/**
+ * XPCOMUtils contains helpers to make lazily loading scripts, modules, prefs
+ * and XPCOM services more ergonomic for JS consumers.
+ *
+ * @class
+ */
 export var XPCOMUtils = {
   /**
+   * DEPRECATED!
+   *
+   * Use ChromeUtils.defineLazyGetter instead.
+   *
    * Defines a getter on a specified object that will be created upon first use.
    *
-   * @param aObject
+   * @param {object} aObject
    *        The object to define the lazy getter on.
-   * @param aName
+   * @param {string} aName
    *        The name of the getter to define on aObject.
-   * @param aLambda
+   * @param {Function} aLambda
    *        A function that returns what the getter should return.  This will
    *        only ever be called once.
    */
@@ -54,14 +64,14 @@ export var XPCOMUtils = {
    * Defines a getter on a specified object for a script.  The script will not
    * be loaded until first use.
    *
-   * @param aObject
+   * @param {object} aObject
    *        The object to define the lazy getter on.
-   * @param aNames
+   * @param {string|string[]} aNames
    *        The name of the getter to define on aObject for the script.
    *        This can be a string if the script exports only one symbol,
    *        or an array of strings if the script can be first accessed
    *        from several different symbols.
-   * @param aResource
+   * @param {string} aResource
    *        The URL used to obtain the script.
    */
   defineLazyScriptGetter(aObject, aNames, aResource) {
@@ -125,13 +135,13 @@ export var XPCOMUtils = {
    * Defines a getter on a specified object for a service.  The service will not
    * be obtained until first use.
    *
-   * @param aObject
+   * @param {object} aObject
    *        The object to define the lazy getter on.
-   * @param aName
+   * @param {string} aName
    *        The name of the getter to define on aObject for the service.
-   * @param aContract
+   * @param {string} aContract
    *        The contract used to obtain the service.
-   * @param aInterfaceName
+   * @param {string} aInterfaceName
    *        The name of the interface to query the service to.
    */
   defineLazyServiceGetter(aObject, aName, aContract, aInterfaceName) {
@@ -147,9 +157,9 @@ export var XPCOMUtils = {
    * Defines a lazy service getter on a specified object for each
    * property in the given object.
    *
-   * @param aObject
+   * @param {object} aObject
    *        The object to define the lazy getter on.
-   * @param aServices
+   * @param {object} aServices
    *        An object with a property for each service to be
    *        imported, where the property name is the name of the
    *        symbol to define, and the value is a 1 or 2 element array
@@ -174,9 +184,9 @@ export var XPCOMUtils = {
    * Defines a lazy module getter on a specified object for each
    * property in the given object.
    *
-   * @param aObject
+   * @param {object} aObject
    *        The object to define the lazy getter on.
-   * @param aModules
+   * @param {object} aModules
    *        An object with a property for each module property to be
    *        imported, where the property name is the name of the
    *        imported symbol and the value is the module URI.
@@ -192,19 +202,19 @@ export var XPCOMUtils = {
    * preference is read the first time that the property is accessed,
    * and is thereafter kept up-to-date using a preference observer.
    *
-   * @param aObject
+   * @param {object} aObject
    *        The object to define the lazy getter on.
-   * @param aName
+   * @param {string} aName
    *        The name of the getter property to define on aObject.
-   * @param aPreference
+   * @param {string} aPreference
    *        The name of the preference to read.
-   * @param aDefaultPrefValue
+   * @param {any} aDefaultPrefValue
    *        The default value to use, if the preference is not defined.
    *        This is the default value of the pref, before applying aTransform.
-   * @param aOnUpdate
+   * @param {Function} aOnUpdate
    *        A function to call upon update. Receives as arguments
    *         `(aPreference, previousValue, newValue)`
-   * @param aTransform
+   * @param {Function} aTransform
    *        An optional function to transform the value.  If provided,
    *        this function receives the new preference value as an argument
    *        and its return value is used by the getter.
@@ -314,6 +324,16 @@ export var XPCOMUtils = {
 
   /**
    * Defines a non-writable property on an object.
+   *
+   * @param {object} aObj
+   *        The object to define the property on.
+   *
+   * @param {string} aName
+   *        The name of the non-writable property to define on aObject.
+   *
+   * @param {any} aValue
+   *        The value of the non-writable property.
+   *
    */
   defineConstant(aObj, aName, aValue) {
     Object.defineProperty(aObj, aName, {

xpcom/docs/index.rst

@@ -3,6 +3,10 @@ XPCOM
 
 These pages contain documentation for Mozilla's Cross-Platform Component Object Model (XPCOM) module.  It abstracts core systems functionality for cross-platform use.  The component architecture follows the standard COM approach.
 
+
+Consuming XPCOM functionality
+-----------------------------
+
 .. toctree::
    :maxdepth: 1
 
@@ -10,11 +14,26 @@ These pages contain documentation for Mozilla's Cross-Platform Component Object
    stringguide
    refptr
    thread-safety
-   huntingleaks
    collections
-   sorting.md
-   xpidl
-   writing-xpcom-interface
    hashtables
    hashtables_detailed
+   sorting.md
+   xpcomutils
+
+Tooling around XPCOM
+--------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   huntingleaks
+
+Writing new XPCOM interfaces/classes
+------------------------------------
+
+.. toctree::
+   :maxdepth: 1
+
+   xpidl
+   writing-xpcom-interface
    cc-macros

xpcom/docs/xpcomutils.rst

@@ -0,0 +1,12 @@
+XPCOMUtils module
+=================
+
+XPCOMUtils is a utility class that lives in
+:searchfox:`resource://gre/modules/XPCOMUtils.sys.mjs <js/xpconnect/loader/XPCOMUtils.sys.mjs>`.
+
+Its name is a little confusing because it does not live in XPCOM itself,
+but it provides utilities that help JS consumers to make consuming
+``sys.mjs`` modules and XPCOM services/interfaces more ergonomic.
+
+.. js:autoclass:: XPCOMUtils
+  :members: