Bug 713605 - Strongly advise against using contentScript rather than …

…contentScriptFile for complex scripts.; r=@dietrich

doc/dev-guide-source/addon-development/content-scripts/loading.md

@@ -42,6 +42,15 @@ Scripts specified using contentScriptFile are loaded before those specified
 using contentScript. This enables you to load a JavaScript library like jQuery
 by URL, then pass in a simple script inline that can use jQuery.
 
+<div class="warning">
+<p>Unless your content script is extremely simple and consists only of a
+static string, don't use <code>contentScript</code>: if you do, you may
+have problems getting your add-on approved on AMO.</p>
+<p>Instead, keep the script in a separate file and load it using
+<code>contentScriptFile</code>. This makes your code easier to maintain,
+secure, debug and review.</p>
+</div>
+
 The `contentScriptWhen` option specifies when the content script(s) should be
 loaded. It takes one of three possible values:
 

doc/static-files/css/sdk-docs.css

@@ -154,8 +154,8 @@ h2 {
   padding: 1em;
   border: solid 2px black;
   width: 75%;
-  background-color: #c63717;
-  color: white;
+  background-color: #FBEDED;
+  border: 1px solid #AC6262;
 }
 
 .logo {

packages/addon-kit/docs/context-menu.md

@@ -309,6 +309,15 @@ create your content scripts in separate files and pass their URLs using the
 [Working with Content Scripts](dev-guide/addon-development/web-content.html)
 for more information.
 
+<div class="warning">
+<p>Unless your content script is extremely simple and consists only of a
+static string, don't use <code>contentScript</code>: if you do, you may
+have problems getting your add-on approved on AMO.</p>
+<p>Instead, keep the script in a separate file and load it using
+<code>contentScriptFile</code>. This makes your code easier to maintain,
+secure, debug and review.</p>
+</div>
+
 Show an "Edit Page Source" item when the user right-clicks a non-interactive
 part of the page:
 

packages/addon-kit/docs/page-mod.md

@@ -70,7 +70,7 @@ then the content script can interact with the DOM itself:
 Most of the examples in this page define content scripts as strings,
 and use the `contentScript` option to assign them to page mods.
 
-In your code you will more often create content scripts in separate files
+Alternatively, you can create content scripts in separate files
 under your add-on's `data` directory. Then you can use the
 [`self`](packages/addon-kit/docs/self.html) module to retrieve a URL pointing
 to the file, and assign this to the page-mod's `contentScriptFile`
@@ -89,6 +89,15 @@ code like:
       contentScriptFile: data.url("myScript.js")
     });
 
+<div class="warning">
+<p>Unless your content script is extremely simple and consists only of a
+static string, don't use <code>contentScript</code>: if you do, you may
+have problems getting your add-on approved on AMO.</p>
+<p>Instead, keep the script in a separate file and load it using
+<code>contentScriptFile</code>. This makes your code easier to maintain,
+secure, debug and review.</p>
+</div>
+
 ## Communicating With Content Scripts ##
 
 When a matching page is loaded the `PageMod` will call the function that the

packages/addon-kit/docs/page-worker.md

@@ -83,6 +83,15 @@ the `contentScript` property. In your own add-ons, you will probably want to
 create your content scripts in separate files and pass their URLs using the
 `contentScriptFile` property.
 
+<div class="warning">
+<p>Unless your content script is extremely simple and consists only of a
+static string, don't use <code>contentScript</code>: if you do, you may
+have problems getting your add-on approved on AMO.</p>
+<p>Instead, keep the script in a separate file and load it using
+<code>contentScriptFile</code>. This makes your code easier to maintain,
+secure, debug and review.</p>
+</div>
+
 To learn much more about content scripts, see the
 [Working with Content Scripts](dev-guide/addon-development/web-content.html)
 guide.

packages/addon-kit/docs/panel.md

@@ -106,7 +106,15 @@ add-on script receives them using `panel.port.on()`.
 This example uses `contentScript` to supply the script as a string. It's
 usually better practice to use `contentScriptFile`, which is a URL pointing
 to a script file saved under your add-on's `data` directory.
-That's what the next example does.
+
+<div class="warning">
+<p>Unless your content script is extremely simple and consists only of a
+static string, don't use <code>contentScript</code>: if you do, you may
+have problems getting your add-on approved on AMO.</p>
+<p>Instead, keep the script in a separate file and load it using
+<code>contentScriptFile</code>. This makes your code easier to maintain,
+secure, debug and review.</p>
+</div>
 
 <img class="image-right" src="static-files/media/screenshots/text-entry-panel.png"
 alt="Text entry panel">

packages/addon-kit/docs/widget.md

@@ -88,6 +88,15 @@ have to send messages between the content script and the main add-on code.
 API or (preferably, usually) the
 [`port`](dev-guide/addon-development/content-scripts/using-port.html) API.
 
+<div class="warning">
+<p>Unless your content script is extremely simple and consists only of a
+static string, don't use <code>contentScript</code>: if you do, you may
+have problems getting your add-on approved on AMO.</p>
+<p>Instead, keep the script in a separate file and load it using
+<code>contentScriptFile</code>. This makes your code easier to maintain,
+secure, debug and review.</p>
+</div>
+
 <!-- The icons this widget displays, shown in the screenshot, is taken from the
 Glossy Buttons icon set created by IconEden which is made freely available for
 commercial and non-commercial use.