657212 - Documentation unclear on difference between data and lib.

Status: RESOLVED FIXED

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

Description

[Paul Biggar]

The documentation is unclear on when I should put my code into data/ and when it should go in lib/. As I understand it, data/ is for content scripts, and lib/ is for chrome scripts. That's really unclear, and it has led me to all sorts of problems, especially when I tried to refactor my data/ scripts into CommonJS packages, and when I tried to use API packages in my data/ scripts.

I'm unclear how the documentation should be refactored to help here, but I hope it can be made clearer.

Comment 1

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

Will: any thoughts on how we can make this clearer?

Comment 2

[Will Bamberg [:wbamberg]]

(In reply to comment #1)
> Will: any thoughts on how we can make this clearer?

I think there are a couple of things in here:
1- what sorts of JavaScripts live under lib/ and data/
2- which APIs the different sorts of scripts are allowed to access (in particular: that 'add-on code'(I'd love a better name for this) can't access the DOM, and content scripts can't access module APIs)

Especially the second of these causes newcomers lots of pain, and we should do a better job of explaining it. 

When we introduce the add-on directory structure in https://jetpack.mozillalabs.com/sdk/1.0b5/docs/dev-guide/addon-development/implementing-simple-addon.html, we should certainly indicate that data/ is for content scripts. But that doesn't sound like the right place to elaborate on (2), it will slow things down too much when we really want to keep moving.

So I think I'd suggest a separate guide outlining (2), that we can link to from elsewhere. This can be pretty short, and represent a step towards fixing bug 635559.

I'd love to get this into 1.0.

Comment 3

[Will Bamberg [:wbamberg]]

Attachment: Explain about add-on scripts versus content scripts

This patch:
- clarifies, in the tutorial, which scripts go under data and which under lib
- adds a programming guide explaining the difference a bit further, especially in terms of the different JavaScript APIs available in each type of script
- recasts the "Globals" reference as just a "Console" reference, because all the other "Globals" content is now in the new guide

Maybe this isn't baked enough to go into 1.0, but I'd like to know what you think about that. I think especially the table is a useful thing.

Comment 4

[Will Bamberg [:wbamberg]]

Oh, also: I don't like the title of the new page much. If you had any better ideas I'd love to hear them.

Comment 5

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

Comment on attachment 535439 [details] [diff] [review]
Explain about add-on scripts versus content scripts

diff --git a/static-files/base.html b/static-files/base.html

+            <li><h4><a href="dev-guide/addon-development/javascript-apis.html">JavaScript APIs in the SDK</a></h4></li>

I would call this Two Types of Scripts.

However, whatever we call it, we should reference it by that name everywhere.  Everywhere else in this patch, the doc is called Which JavaScript APIs Can You Use?, but here it's called JavaScript APIs in the SDK.


diff --git a/static-files/md/dev-guide/addon-development/implementing-simple-addon.md 

+* `/data` contains resources such as icons or strings, as well as any

Since you're here: icons or strings -> icons and HTML files

("HTML files" is more representative of what you might put into data/ than the ambiguous "strings", which might have presupposed a particular l10n implementation that never happened.)


diff --git a/static-files/md/dev-guide/addon-development/javascript-apis.md 

+Usually JavaScript executes in the context of a web page, and has access to
+that page's DOM content. This enables you to call functions like:

Nit: Usually -> On the web,


+## Add-on Code ##
+
+This is the place where the main logic of the add-on is implemented. Add-on
+code is kept somewhere under the `lib` directory under your add-on's root
+directory.
+
+The main script is called "main.js", but you can include additional modules
+in `lib`, and import them using the `require()` function. To learn how to
+implement and import your own modules, see the tutorial on
+[Implementing Reusable Modules](dev-guide/addon-development/implementing-reusable-module.html).

It might be good to talk here about how add-on code comprises a set of JavaScript modules, one of which is your "main module".  But I'm not quite sure how to say it.  The whole "main module" concept is a bit overcomplicated (but fixing that is post-1.0).


+  <tr>
+    <th>API</th>
+    <th>Add-on script</th>

Earlier, you called this "add-on code", but here you call it "add-on script".  It'd be better to call it "add-on code" here too.


+    <td>The global objects defined in
+<a href="https://developer.mozilla.org/En/New_in_JavaScript_1.8.1">JavaScript 1.8.1</a>,
+such as <code>Math</code>, <code>Array</code>, and <code>JSON</code>.

JavaScript is up to 1.8.5, but in any case it would be better to just say "The global objects defined in the core JavaScript language" and link to the latest comprehensive list of global objects, i.e.:

https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects

(Although it's possible that a few of those global objects aren't actually available in modules; I'm looking at you, E4X globals.)


+    <td>All the modules supplied in the SDK, and imported via
+<code>require()</code>. See
+this <a href="dev-guide/addon-development/api-modules.html">quick overview</a>
+of some of the most commonly used modules.

Erm, this is not quite right, because these aren't actually globals.  Unlike some other module systems, require() merely returns a reference to an object containing a set of symbols.  The importing script then assigns it to a variable, which may or may not be a global object.

Rather than making this a separate row, I would instead annotate the previous row to point out that the lack of require() means that content scripts can't import modules supplied by the SDK or by add-on code.


+    <td>Globals defined by the
+<a href="http://dev.w3.org/html5/spec/Overview.html">HTML5</a> specification,
+such as <code>window</code>, <code>document</code>, or
+<code>localStorage</code>.

Nit: or -> and


+    <td>The <code>self</code> global, used for sending events and messages from
+content scripts to add-on scripts. See the guide to

Nit: add-on scripts -> add-on code

However, I would also make this broader change: sending events and messages from content scripts to add-on scripts -> communicating between content scripts and add-on code (as in this doc it isn't particularly important to point out the two ways such communication can take place).


diff --git a/static-files/media/check.png b/static-files/media/check.png
diff --git a/static-files/media/cross.png b/static-files/media/cross.png

Could we use one of the the tick and x mark symbols instead of images?

  http://en.wikipedia.org/wiki/Tick_%28check_mark%29
  http://en.wikipedia.org/wiki/X_mark

Comment 6

[Will Bamberg [:wbamberg]]

Attachment: Addressed review comments

Thanks for the comments, they helped a lot.

Comment 7

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

Comment on attachment 536363 [details] [diff] [review]
Addressed review comments

>diff --git a/static-files/md/dev-guide/addon-development/guides.md b/static-files/md/dev-guide/addon-development/guides.md

>+### [Which JavaScript APIs Can You Use?](dev-guide/addon-development/javascript-apis.html) ###
>+An introduction to the different sorts of scripts you can write, and
>+a summary of which APIs are available to which scripts.

This needs to be updated to the new name for the document/file.

Otherwise, this looks good, r+a=myk with that change.

Comment 8

[Will Bamberg [:wbamberg]]

Landed in: https://github.com/mozilla/addon-sdk/commit/7826485e09617d222744222708ac23b64b6e3b65.