633860 - Packaging docs are missing

Status: RESOLVED FIXED

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

Description

[Fred Wenzel [:wenzel]]

There used to be packaging documentation for stuff like exports.main and exports.onUnload. Those are missing from the latest SDK docs[1] now, it seems.

Some places still link to it[2] (search for "Packaging" on that page), but the link leads nowhere useful.

[1] https://jetpack.mozillalabs.com/sdk/1.0b2/docs/
[2] https://jetpack.mozillalabs.com/sdk/1.0b2/docs/#guide/globals

Comment 1

[Will Bamberg [:wbamberg]]

Attachment: Reinstated description of 'exports.main' and 'exports.onUnload'

The packaging docs are mostly replaced with the translator example. One part that went missing is the stuff on exports.main and exports.onUnload, which I've reinstated here.

Comment 2

[Fred Wenzel [:wenzel]]

Cool, thanks. Please also make sure to grep for "packaging" in the docs, to remove those dead links (or rather, point them to where that part of the docs moved).

Comment 3

[Brian Warner [:warner :bwarner]]

Comment on attachment 512224 [details] [diff] [review]
Reinstated description of 'exports.main' and 'exports.onUnload'

Looks good to me. My only thought is on the use of the word "program" to
describe the addon, as in:

 If your program exports a function called `main`, that function will be
 called when your program is loaded.

While it's accurate to call addons "programs", it strikes me as a bit weird:
different pieces of your "program" are going to be run at various times,
unlike a more traditional hello-world.c sort of program. But I'm happy with
it.

Would it be worthwhile to explain when the top-level code of your module will
be run? (as illustrated by the old version of the example, which didn't use
exports.main). Also, should we explain what the various
install/enable/startup/upgrade/downgrade/uninstall/disable/shutdown reasons
mean? I doubt we'd want to get into that much detail in this document, but
maybe a pointer to some MDC page explaining the reason strings would be
helpful.

Comment 4

[Will Bamberg [:wbamberg]]

Thanks.

> Would it be worthwhile to explain when the top-level code of your module will
> be run? (as illustrated by the old version of the example, which didn't use
> exports.main).

Yes, it would, but I'm not sure what the answer is. As far as I can tell it's the same: it gets run at install/startup/upgrade/downgrade/enable - it's just that you get the reason string in exports.main. I think it would be helpful to give some best practice advice on which you should choose here and when, but it's not very clear to me unfortunately (I would guess: use exports.main if you need to distinguish these reasons).

> Also, should we explain what the various
> install/enable/startup/upgrade/downgrade/uninstall/disable/shutdown reasons
> mean? I doubt we'd want to get into that much detail in this document, but
> maybe a pointer to some MDC page explaining the reason strings would be
> helpful.

Yes. If I can find such a thing I'll include it.

Comment 5

[Will Bamberg [:wbamberg]]

 
> Yes. If I can find such a thing I'll include it.

https://developer.mozilla.org/en/Extensions/Bootstrapped_extensions#Reason_constants

Comment 6

[Will Bamberg [:wbamberg]]

(In reply to comment #2)
> Cool, thanks. Please also make sure to grep for "packaging" in the docs, to
> remove those dead links (or rather, point them to where that part of the docs
> moved).

Yes: the link you mentioned in the bug report is fixed now, I believe.

As far as I could see, the only place that still links to 'Packaging" is https://jetpack.mozillalabs.com/sdk/1.0b2/docs/#guide/xul-extensions, but the instructions on that page don't work at all any more, so I think in this release we should flag that (see bug 633625).

Comment 7

[Drew Willcoxon :adw]

(In reply to comment #4)
> > Would it be worthwhile to explain when the top-level code of your module will
> > be run? (as illustrated by the old version of the example, which didn't use
> > exports.main).
> 
> Yes, it would, but I'm not sure what the answer is.

Several people on the mailing list have been confused about when their add-on code is run, in what scope, and how to "run" it again, so some brief discussion about all of that would be great (as a follow-up bug).  And it ties into the `reason` strings nicely.

(In reply to comment #5)
> > Yes. If I can find such a thing I'll include it.
> 
> https://developer.mozilla.org/en/Extensions/Bootstrapped_extensions#Reason_constants

Just to be clear, `reason` is a string, not an integer, and since this page doesn't provide any explanation beyond what you can assume from the various values of the string, I think linking to this page wouldn't be helpful and might even confuse people.

A drive-by comment on the patch:  It looks like reasons are logged to the console in the implementing-reusable-module.md example, but it's not explained anywhere why.  reason strings are an "add-on level" topic, not really a "module-level" topic, so I don't think this doc is a particularly good place to illustrate them.  (implementing-simple-addon.md, OTOH, is right on.)

Comment 8

[Will Bamberg [:wbamberg]]

 
> (In reply to comment #5)
> > > Yes. If I can find such a thing I'll include it.
> > 
> > https://developer.mozilla.org/en/Extensions/Bootstrapped_extensions#Reason_constants
> 
> Just to be clear, `reason` is a string, not an integer, and since this page
> doesn't provide any explanation beyond what you can assume from the various
> values of the string, I think linking to this page wouldn't be helpful and
> might even confuse people.

OK, so I think the best thing to do for 1.0b3 is not to include a discussion of what these strings mean.

> A drive-by comment on the patch:  It looks like reasons are logged to the
> console in the implementing-reusable-module.md example, but it's not explained
> anywhere why.  reason strings are an "add-on level" topic, not really a
> "module-level" topic, so I don't think this doc is a particularly good place to
> illustrate them.  (implementing-simple-addon.md, OTOH, is right on.)

The only reason this is included in implementing-reusable-module.md is that implementing-reusable-module.md is based on implementing-simple-addon.md. It seemed clearer to change only what needed changing to factor out the 'translate' function, than to make other changes not relevant to the purpose of the chapter. But if it seems less clear this way it's obviously simple to change it.

Comment 9

[Drew Willcoxon :adw]

(In reply to comment #8)
> The only reason this is included in implementing-reusable-module.md is that
> implementing-reusable-module.md is based on implementing-simple-addon.md. It
> seemed clearer to change only what needed changing to factor out the
> 'translate' function, than to make other changes not relevant to the purpose of
> the chapter.

Ah, I didn't realize that code came from the earlier example add-on.  Please ignore me. :)

Comment 10

[Will Bamberg [:wbamberg]]

Fixed by: https://github.com/mozilla/addon-sdk/commit/36c708f9a4c83a24a8d3381f07648bdda8c802e2