552109 - Write documentation for the jetpack-core/xpcom module

Status: RESOLVED FIXED

(Add-on SDK Graveyard :: Documentation, defect, P2)

Description

[Drew Willcoxon :adw]

Write documentation for the jetpack-core/xpcom module.  Note that there were changes made in bug 551821.  Setting target milestone as 0.2, someone feel free to correct me.

Comment 1

[Myk Melez [:myk] [@mykmelez]]

It would be good to get this documented for 0.3.  Noelle: Atul suggested that this is something you might be already working on.  Is that correct?

Comment 2

[Noelle Murata]

Myk: have started working on this, I think I will be able to have something sharable for 0.3.

Comment 3

[Myk Melez [:myk] [@mykmelez]]

Thanks Noelle!  Setting you as the assignee, then.

Comment 4

[Drew Willcoxon :adw]

Noelle, any update?  I can take this off your plate if you'd like.

Comment 5

[Myk Melez [:myk] [@mykmelez]]

The Add-on SDK is no longer a Mozilla Labs experiment and has become a big enough project to warrant its own Bugzilla product, so the "Add-on SDK" product has been created for it, and I am moving its bugs to that product.

To filter bugmail related to this change, filter on the word "looptid".

Comment 6

[Myk Melez [:myk] [@mykmelez]]

(automatic reprioritization of 1.0 bugs)

Comment 7

[Will Bamberg [:wbamberg]]

Resetting the priority of this, as module development documentation is not P1.

Comment 8

[Wes Kocher (:KWierso) (Not reading bugmail; email directly if needed)]

(Pushing all open bugs to the --- milestone for the new triage system)

Comment 9

[Wes Kocher (:KWierso) (Not reading bugmail; email directly if needed)]

Drew, did you ever get a chance to write something up for this? Anything (that isn't untrue!) would be better than the nothing that's there currently, in my opinion.

Reason I'm asking is that I've been seeing someone on IRC ask how to use the xpcom module, and I really have no clue myself, since the docs are non-existent.

Comment 10

[Drew Willcoxon :adw]

No, I never did write anything.  Probably the best way right now to learn how xpcom.js works is to study its exported objects and test/test-xpcom.js.

Comment 11

[Will Bamberg [:wbamberg]]

Attachment: Some docs for xpcom

There is an exported function called autoRegister that I didn't document because it isn't used anywhere and doesn't have a unit test. I guess we should write a unit test and document it, or remove it.

I'm not very familiar with XPCOM component creation, and the existing docs are quite hard going, and I didn't want this to turn into an XPCOM component creation tutorial. But this patch should be a reasonable start, anyway.

Comment 12

[Drew Willcoxon :adw]

Comment on attachment 568270 [details] [diff] [review]
Some docs for xpcom

Review of attachment 568270 [details] [diff] [review]:
-----------------------------------------------------------------

Thanks Will.  Lots of comments but this XPCOM stuff is hopelessly complicated. :\

Before I start, totally unrelated:  The "ADD-ON SDK" wordmark next to the Firefox logo in the top left is rendered in the default serif font, both with cfx docs and on AMO.  Wasn't it using a different and much nicer font until recently?

::: packages/api-utils/docs/xpcom.md
@@ -3,1 +3,10 @@
> > -It still needs to be documented.
> > +* register a component with
> > +[XPCOM](https://developer.mozilla.org/en/Creating_XPCOM_Components),
> > +making it available to all XPCOM clients
> > +* retrieve a factory for a given XPCOM component
NaN more ...

Somewhere this doc should link to https://developer.mozilla.org/en/How_to_Build_an_XPCOM_Component_in_Javascript.

@@ -3,1 +3,19 @@
> > -It still needs to be documented.
> > +* register a component with
> > +[XPCOM](https://developer.mozilla.org/en/Creating_XPCOM_Components),
> > +making it available to all XPCOM clients
> > +* retrieve a factory for a given XPCOM component
NaN more ...

Use emdashes (—) here instead of hyphens, or at least two hyphens (--).  Better yet, reword, "This function creates and registers a factory for a component given its metadata: a class ID, a contract ID, and a name."

Add, "The factory is used to create instances of the component."

@@ -3,1 +3,26 @@
> > -It still needs to be documented.
> > +* register a component with
> > +[XPCOM](https://developer.mozilla.org/en/Creating_XPCOM_Components),
> > +making it available to all XPCOM clients
> > +* retrieve a factory for a given XPCOM component
NaN more ...

"How do I make Ci.nsIHelloWorld?" the reader will ask.  A couple of options:  1) Instead of implementing a custom interface, this example should implement an interface that already exists in Gecko, something small like nsIAboutModule, as test-xpcom.js does.  2) Most readers are probably interested in using custom components only from JS, so use the technique described under the "Using wrappedJSObject" section of the aforelinked How_to_Build_an_XPCOM_Component_in_Javascript MDN page.  (I assume it works with the SDK and the xpcom module.  I haven't tested.)

@@ -3,1 +3,33 @@
> > -It still needs to be documented.
> > +* register a component with
> > +[XPCOM](https://developer.mozilla.org/en/Creating_XPCOM_Components),
> > +making it available to all XPCOM clients
> > +* retrieve a factory for a given XPCOM component
NaN more ...

Use a non-mozilla.org, non-addonSDK contract ID here, like you do in the Factory example, to make it clear to people copying and pasting this example that they can and should use their own IDs for custom components.

@@ +40,5 @@
> +
> +    var factory = require("xpcom").getClass("@mozilla.org/addonSDK/helloworld",
> +                                            Ci.nsIFactory);
> +    var helloWorld = factory.createInstance(null, Ci.nsIHelloWorld);
> +    helloWorld.hello();

helloWorld.hello() only returns a string, so to make this example more complete, console.log() the returned string or change the hello() implementation to log it.

@@ -3,1 +3,46 @@
> > -It still needs to be documented.
> > +* register a component with
> > +[XPCOM](https://developer.mozilla.org/en/Creating_XPCOM_Components),
> > +making it available to all XPCOM clients
> > +* retrieve a factory for a given XPCOM component
NaN more ...

Reword, "register returns a Factory object for the component which implements the createInstance and QueryInterface functions of the nsIFactory and nsISupports interfaces, as well as..."

@@ -3,1 +3,94 @@
> > -It still needs to be documented.
> > +* register a component with
> > +[XPCOM](https://developer.mozilla.org/en/Creating_XPCOM_Components),
> > +making it available to all XPCOM clients
> > +* retrieve a factory for a given XPCOM component
NaN more ...

iid's aren't strings... I guess "object" would be better?  Or maybe just "iid".  You might want to add that these are the things that hang off Ci.

@@ -3,1 +3,96 @@
> > -It still needs to be documented.
> > +* register a component with
> > +[XPCOM](https://developer.mozilla.org/en/Creating_XPCOM_Components),
> > +making it available to all XPCOM clients
> > +* retrieve a factory for a given XPCOM component
NaN more ...

Reword, "The methods of this interface will be callable on the returned factory object.  Usually you want this to be Ci.nsIFactory, but if you know a component has a factory that implements a more specific type of factory interface, you can pass that interface here.  If you don't include this option only the methods of nsISupports will be callable, which is probably not what you want."

@@ -3,1 +3,98 @@
> > -It still needs to be documented.
> > +* register a component with
> > +[XPCOM](https://developer.mozilla.org/en/Creating_XPCOM_Components),
> > +making it available to all XPCOM clients
> > +* retrieve a factory for a given XPCOM component
NaN more ...

Object -> object

@@ -3,1 +3,101 @@
> > -It still needs to be documented.
> > +* register a component with
> > +[XPCOM](https://developer.mozilla.org/en/Creating_XPCOM_Components),
> > +making it available to all XPCOM clients
> > +* retrieve a factory for a given XPCOM component
NaN more ...

The type of this -> The type of this object

Add, "Note that this is not a Factory object as defined by this module.  If you previously registered the component by calling the register function and you need to access the Factory object for the component, for example to call the Factory's unregister method, you can do so by getting the wrappedJSObject property of the returned object."

@@ -3,1 +3,115 @@
> > -It still needs to be documented.
> > +* register a component with
> > +[XPCOM](https://developer.mozilla.org/en/Creating_XPCOM_Components),
> > +making it available to all XPCOM clients
> > +* retrieve a factory for a given XPCOM component
NaN more ...

uuid -> UUID

Add, "Calling toString() on this object will yield the UUID in string form."

@@ -3,1 +3,128 @@
> > -It still needs to be documented.
> > +* register a component with
> > +[XPCOM](https://developer.mozilla.org/en/Creating_XPCOM_Components),
> > +making it available to all XPCOM clients
> > +* retrieve a factory for a given XPCOM component
NaN more ...

Nit: style is weird, maybe try:

  var myFactory = require("xpcom").register({
    name: "My Component",
    contractID: "@me.org/myComponent",
    create: MyComponent
  });

@@ -3,1 +3,134 @@
> > -It still needs to be documented.
> > +* register a component with
> > +[XPCOM](https://developer.mozilla.org/en/Creating_XPCOM_Components),
> > +making it available to all XPCOM clients
> > +* retrieve a factory for a given XPCOM component
NaN more ...

Reword, "Factory implements a key function from nsIFactory, createInstance.  (It does not currently implement lockFactory.)"

(QueryInterface isn't really important to consumers of this API.)

@@ -3,1 +3,145 @@
> > -It still needs to be documented.
> > +* register a component with
> > +[XPCOM](https://developer.mozilla.org/en/Creating_XPCOM_Components),
> > +making it available to all XPCOM clients
> > +* retrieve a factory for a given XPCOM component
NaN more ...

NS_ERROR_NO_AGGREGATION -> Cr.NS_ERROR_NO_AGGREGATION

@@ -3,1 +3,147 @@
> > -It still needs to be documented.
> > +* register a component with
> > +[XPCOM](https://developer.mozilla.org/en/Creating_XPCOM_Components),
> > +making it available to all XPCOM clients
> > +* retrieve a factory for a given XPCOM component
NaN more ...

iid's aren't strings, same as above.

@@ -3,1 +3,149 @@
> > -It still needs to be documented.
> > +* register a component with
> > +[XPCOM](https://developer.mozilla.org/en/Creating_XPCOM_Components),
> > +making it available to all XPCOM clients
> > +* retrieve a factory for a given XPCOM component
NaN more ...

Reword, "The methods of this interface will be callable on the returned object.  Usually you want this to be the primary interface that the component implements, or at least the one you want to use.  If you will be getting the wrappedJSObject property from the returned object to access its JavaScript implementation, you don't have to specify this parameter."

(I think that last sentence is true...)

@@ -3,1 +3,156 @@
> > -It still needs to be documented.
> > +* register a component with
> > +[XPCOM](https://developer.mozilla.org/en/Creating_XPCOM_Components),
> > +making it available to all XPCOM clients
> > +* retrieve a factory for a given XPCOM component
NaN more ...

Reword, "This method is called automatically by XPCOM, so usually you don't need to call it yourself.  It returns the Factory object itself such that the methods of the given interface are callable on it."

@@ -3,1 +3,158 @@
> > -It still needs to be documented.
> > +* register a component with
> > +[XPCOM](https://developer.mozilla.org/en/Creating_XPCOM_Components),
> > +making it available to all XPCOM clients
> > +* retrieve a factory for a given XPCOM component
NaN more ...

This only takes one interface, so an iid again.  (XPCOMUtils.generateQI takes an array of interfaces, but it returns a function that takes only one interface.)

@@ -3,1 +3,160 @@
> > -It still needs to be documented.
> > +* register a component with
> > +[XPCOM](https://developer.mozilla.org/en/Creating_XPCOM_Components),
> > +making it available to all XPCOM clients
> > +* retrieve a factory for a given XPCOM component
NaN more ...

Reword, "There are only two legal values for this parameter: Ci.nsIFactory and Ci.nsISupports.  Any other value will cause this method to throw Cr.NS_ERROR_NO_INTERFACE."

@@ -3,1 +3,167 @@
> > -It still needs to be documented.
> > +* register a component with
> > +[XPCOM](https://developer.mozilla.org/en/Creating_XPCOM_Components),
> > +making it available to all XPCOM clients
> > +* retrieve a factory for a given XPCOM component
NaN more ...

You should mention either here or in register() that when the module is unloaded, all components registered via the register function are automatically unregistered.

Comment 13

[Drew Willcoxon :adw]

Uh, wha happened.  I'll try again, not using splinter this time...

>+Using this module you can:

Somewhere this doc should link to https://developer.mozilla.org/en/How_to_Build_an_XPCOM_Component_in_Javascript.

>+<api name="register">
>+@function
>+
>+Makes a component available through XPCOM.
>+
>+Given a constructor for a component and some XPCOM metadata - a
>+[class ID](https://developer.mozilla.org/en/Creating_XPCOM_Components/An_Overview_of_XPCOM#CID), a
>+[contract ID](https://developer.mozilla.org/en/Creating_XPCOM_Components/An_Overview_of_XPCOM#Contract_ID)
>+and a name - this function creates and registers a factory for the component:

Use emdashes (&mdash;) here instead of hyphens, or at least two hyphens (--).  Better yet, reword, "This function creates and registers a factory for a component given its metadata: a class ID, a contract ID, and a name."

Add, "The factory is used to create instances of the component."

>+
>+    var xpcom = require("xpcom");
>+
>+    function HelloWorld() {}
>+
>+    HelloWorld.prototype = {
>+      QueryInterface: xpcom.utils.generateQI([Ci.nsIHelloWorld]),

"How do I make Ci.nsIHelloWorld?" the reader will ask.  A couple of options:  1) Instead of implementing a custom interface, this example should implement an interface that already exists in Gecko, something small like nsIAboutModule, as test-xpcom.js does.  2) Most readers are probably interested in using custom components only from JS, so use the technique described under the "Using wrappedJSObject" section of the aforelinked How_to_Build_an_XPCOM_Component_in_Javascript MDN page.  (I assume it works with the SDK and the xpcom module.  I haven't tested.)

>+      hello: function() {
>+        return "Hello World!";
>+      }
>+    };
>+
>+    xpcom.register({name: "Hello World Component",
>+                    contractID: "@mozilla.org/addonSDK/helloworld",

Use a non-mozilla.org, non-addonSDK contract ID here, like you do in the Factory example, to make it clear to people copying and pasting this example that they can and should use their own IDs for custom components.

>+                    create: HelloWorld});
>+
>+XPCOM clients can subsequently access this factory and use it to create
>+instances of the component.
>+
>+    var factory = require("xpcom").getClass("@mozilla.org/addonSDK/helloworld",
>+                                            Ci.nsIFactory);
>+    var helloWorld = factory.createInstance(null, Ci.nsIHelloWorld);
>+    helloWorld.hello();

helloWorld.hello() only returns a string, so to make this example more complete, console.log() the returned string or change the hello() implementation to log it.

>+`register()` returns a `Factory` object for the class, which wraps the
>+[`nsIFactory`](https://developer.mozilla.org/en/XPCOM_Interface_Reference/nsIFactory)
>+`QueryInterface()` and `createInstance()` functions, as well as defining an
>+`unregister()` function to remove the component from XPCOM.

Reword, "register returns a Factory object for the component which implements the createInstance and QueryInterface functions of the nsIFactory and nsISupports interfaces, as well as..."

>+<api name="getClass">
>+@function
>+Returns the factory object for the class specified by `contractID`.
>+
>+For example, given a registered XPCOM component which:
>+
>+* is identified with the contract ID "@me.org/myComponent"
>+* implements the interface `nsIMyInterface`
>+
>+we can access a factory and then use it to instantiate the component in the
>+following way:
>+
>+    var myFactory = xpcom.getClass("@me.org/myComponent", Ci.nsIFactory);
>+    var myComponent = myFactory.createInstance(null, Ci.nsIMyInterface);
>+
>+@param contractID {string}
>+The
>+[contract ID](https://developer.mozilla.org/en/Creating_XPCOM_Components/An_Overview_of_XPCOM#Contract_ID)
>+for the component whose factory will be returned.
>+
>+@param [iid] {string}

iid's aren't strings...  I guess "object" would be better?  Or maybe just "iid".  You might want to add that these are the things that hang off Ci.

>+The interface type to be returned. If you don't include this option
>+[`nsISupports`](https://developer.mozilla.org/En/NsISupports) is returned.

Reword, "The methods of this interface will be callable on the returned factory object.  Usually you want this to be Ci.nsIFactory, but if you know a component has a factory that implements a more specific type of factory interface, you can pass that interface here.  If you don't include this option only the methods of nsISupports will be callable, which is probably not what you want."

>+
>+@returns {Object}

Object -> object

>+The factory object. The type of this will depend on the value of the `iid`
>+argument. If no `iid` argument is specified it will be of type
>+[`nsISupports`](https://developer.mozilla.org/En/NsISupports).

The type of this -> The type of this object

Add, "Note that this object is not a Factory object as defined by this module.  If you previously registered the component by calling the register function and you need to access the Factory object for the component, for example to call the Factory's unregister method, you can do so by getting the wrappedJSObject property of the returned object."

>+
>+</api>
>+
>+<api name="utils">
>+@property {object}
>+The
>+[XPCOMUtils](https://developer.mozilla.org/en/JavaScript_code_modules/XPCOMUtils.jsm)
>+module.
>+</api>
>+
>+<api name="makeUuid">
>+@function
>+Generates and returns a new
>+[uuid](https://developer.mozilla.org/en/Generating_GUIDs).

uuid -> UUID

Add, "Calling toString() on this object will yield the UUID in string form."

>+@returns {nsIDPtr}
>+</api>
>+
>+<api name="Factory">
>+@class
>+
>+When a component is made available through XPCOM using the `register()`
>+function, `register()` returns a `Factory` object that can be used to
>+instantiate the component:
>+
>+    var myFactory = require("xpcom").register({name: "My Component",
>+                           contractID: "@me.org/myComponent",
>+                           create: MyComponent});

Nit, style is weird, maybe try:

  var myFactory = require("xpcom").register({
    name: "My Component",
    contractID: "@me.org/myComponent",
    create: MyComponent
  });

>+
>+    var myComponent = myFactory.createInstance(null, Ci.nsIMyComponent);
>+
>+`Factory` wraps two key functions from
>+[`nsIFactory`](https://developer.mozilla.org/en/XPCOM_Interface_Reference/nsIFactory):
>+`createInstance()` and `QueryInterface()`.

Reword, "Factory implements a key function from nsIFactory, createInstance.  (It does not currently implement lockFactory.)"

(QueryInterface isn't really important to consumers of this API.)

>+
>+It also implements its own `unregister()` function,
>+which removes the factory from XPCOM's registry.
>+
>+<api name="createInstance">
>+@method
>+Creates an instance of the component associated with this factory.
>+
>+@param outer {nsISupports}
>+This argument must be `null`, or the function throws
>+`NS_ERROR_NO_AGGREGATION`.

NS_ERROR_NO_AGGREGATION -> Cr.NS_ERROR_NO_AGGREGATION

>+
>+@param iid {string}

iid's aren't strings, same as above.

>+The interface ID of the interface being requested in the component
>+to be created.

Reword, "The methods of this interface will be callable on the returned object.  Usually you want this to be the primary interface that the component implements, or at least the one you want to use.  If you will be getting the wrappedJSObject property from the returned object to access its JavaScript implementation, you don't have to specify this parameter."

(I think that last sentence is true...)

>+
>+</api>
>+
>+<api name="QueryInterface">
>+@method
>+Returns `this`, if the `interfaces` argument contains the interface ID for
>+`nsIFactory`. Otherwise returns `null`.

Reword, "This method is called automatically by XPCOM, so usually you don't need to call it yourself.  It returns the Factory object itself such that the methods of the given interface are callable on it."

>+
>+@param interfaces {array}
>+An array of interface IDs. If the array contains the interface ID for
>+`nsIFactory`, then `this` is returned.

This only takes one interface, so an iid again.  (XPCOMUtils.generateQI takes an array of interfaces, but it returns a function that takes only one interface.)

Reword, "There are only two legal values for this parameter: Ci.nsIFactory and Ci.nsISupports.  Any other value will cause this method to throw Cr.NS_ERROR_NO_INTERFACE."

>+
>+@returns {Factory}
>+</api>
>+
>+<api name="unregister">
>+@method
>+Removes the factory from XPCOM's registry.

You should mention either here or in register() that when the module is unloaded, all components registered via the register function are automatically unregistered.

Comment 14

[Will Bamberg [:wbamberg]]

(In reply to Drew Willcoxon :adw from comment #12)
> Comment on attachment 568270 [details] [diff] [review] [diff] [details] [review]
> Some docs for xpcom
> 
> Review of attachment 568270 [details] [diff] [review] [diff] [details] [review]:
> -----------------------------------------------------------------
> 
> Thanks Will.  Lots of comments but this XPCOM stuff is hopelessly
> complicated. :\
> 
> Before I start, totally unrelated:  The "ADD-ON SDK" wordmark next to the
> Firefox logo in the top left is rendered in the default serif font, both
> with cfx docs and on AMO.  Wasn't it using a different and much nicer font
> until recently?

Yup, see bug 695987. Thanks for the comments!

Comment 15

[Will Bamberg [:wbamberg]]

> >+
> >+    var xpcom = require("xpcom");
> >+
> >+    function HelloWorld() {}
> >+
> >+    HelloWorld.prototype = {
> >+      QueryInterface: xpcom.utils.generateQI([Ci.nsIHelloWorld]),
> 
> "How do I make Ci.nsIHelloWorld?" the reader will ask.  A couple of options:
> 1) Instead of implementing a custom interface, this example should implement
> an interface that already exists in Gecko, something small like
> nsIAboutModule, as test-xpcom.js does.  2) Most readers are probably
> interested in using custom components only from JS, so use the technique
> described under the "Using wrappedJSObject" section of the aforelinked
> How_to_Build_an_XPCOM_Component_in_Javascript MDN page.  (I assume it works
> with the SDK and the xpcom module.  I haven't tested.)

I can get this to work if the code to retrieve it looks like this:

    var helloWorld = Cc["@me.org/myComponent"]
                     .getService().wrappedJSObject;
    console.log(helloWorld.hello());

(see https://builder.addons.mozilla.org/addon/1022310/revision/1/) 
...but I don't know how to retrieve it using either (1) the xpcom.getClass() function, or (2) the createInstance method of the Factory returned by register(). Could you briefly explain to me how I should do that?

Thanks!

Comment 16

[Drew Willcoxon :adw]

Thanks for trying it out.  This works:

  var factory = xpcom.register({name: "Hello World Component",
                                contractID: "@me.org/myComponent",
                                create: HelloWorld});
  // Or:
  // var factory = xpcom.getClass("@me.org/myComponent", Ci.nsIFactory);
  var helloWorld = factory.createInstance(null, Ci.nsISupports).wrappedJSObject;
  console.log(helloWorld.hello());

Which means what I said earlier about createInstance's iid parameter is wrong:

> >+The interface ID of the interface being requested in the component
> >+to be created.
> 
> Reword, "The methods of this interface will be callable on the returned
> object.  Usually you want this to be the primary interface that the
> component implements, or at least the one you want to use.  If you will be
> getting the wrappedJSObject property from the returned object to access its
> JavaScript implementation, you don't have to specify this parameter."
> 
> (I think that last sentence is true...)

So it should be like, "If you will be getting the wrappedJSObject property from the returned object to access its JavaScript implementation, pass Ci.nsISupports."

Comment 17

[Will Bamberg [:wbamberg]]

Attachment: A new patch

Comment 18

[Drew Willcoxon :adw]

Comment on attachment 569443 [details] [diff] [review]
A new patch

Review of attachment 569443 [details] [diff] [review]:
-----------------------------------------------------------------

Thanks for finishing this up, Will.

::: packages/api-utils/docs/xpcom.md
@@ +11,5 @@
> +module.
> +
> +The guide to
> +[building XPCOM components in JavaScript](https://developer.mozilla.org/en/How_to_Build_an_XPCOM_Component_in_Javascript)
> +will help you understand how to use this module.

That page explains how to create a component in JavaScript, which doesn't really help people who may find the xpcom module useful but don't need to create components.  You could reword this, but I think the second and third links below are sufficient and included in the relevant contexts.

@@ +109,5 @@
> +
> +@param [iid] {iid}
> +The interface type to be returned. These objects are usually accessed through
> +the `Components.interfaces`, or `Ci`, object. If you don't include this option
> +[`nsISupports`](https://developer.mozilla.org/En/NsISupports) is returned.

nsISupports isn't returned but an object whose only methods are those of nsISupports.  I think the following paragraph explains it well enough.

@@ +176,5 @@
> +to retrieve the component. For more details on this technique see the
> +[guide to building XPCOM components in JavaScript](https://developer.mozilla.org/en/How_to_Build_an_XPCOM_Component_in_Javascript).
> +
> +`Factory` also implements its own `unregister()` function,
> +which removes the factory from XPCOM's registry.

I'd reword, "which unregisters the component from XPCOM," since the component is the important part, and since the register() section rightly talks about making "a component available through XPCOM."

@@ +221,5 @@
> +</api>
> +
> +<api name="unregister">
> +@method
> +Removes the factory from XPCOM's registry.

Same here.  "Unregisters the factory's component" or something like that.

Comment 19

[Will Bamberg [:wbamberg]]

Thanks Drew! Landed as: https://github.com/mozilla/addon-sdk/commit/9969483d62012339ef24743ca63e2bca18da7bff.

Comment 20

[Myk Melez [:myk] [@mykmelez]]

https://github.com/mozilla/addon-sdk/commit/50423abca114420caf3e21300c0c638cdc6e31a0