diff --git a/.eslintrc-rollouts.js b/.eslintrc-rollouts.js index ef4b7d9b13d5..9580e1c79180 100644 --- a/.eslintrc-rollouts.js +++ b/.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/**", diff --git a/docs/conf.py b/docs/conf.py index 9b0c6cf41a57..8991bb095d44 100644 --- a/docs/conf.py +++ b/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", diff --git a/js/xpconnect/loader/ComponentUtils.sys.mjs b/js/xpconnect/loader/ComponentUtils.sys.mjs index cfffb96ef785..3987277ac6e9 100644 --- a/js/xpconnect/loader/ComponentUtils.sys.mjs +++ b/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) { diff --git a/js/xpconnect/loader/XPCOMUtils.sys.mjs b/js/xpconnect/loader/XPCOMUtils.sys.mjs index be60e222a1cf..ac5ac2f66dec 100644 --- a/js/xpconnect/loader/XPCOMUtils.sys.mjs +++ b/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, { diff --git a/xpcom/docs/index.rst b/xpcom/docs/index.rst index 09a51835bc18..6633d4c27392 100644 --- a/xpcom/docs/index.rst +++ b/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 diff --git a/xpcom/docs/xpcomutils.rst b/xpcom/docs/xpcomutils.rst new file mode 100644 index 000000000000..7d21c7330a34 --- /dev/null +++ b/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 `. + +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: