Add discussion of executeScript and insertCSS to the content scripts page.

Point to this discussion from the chrome.tabs API doc.

TEST=none
BUG=28424

Review URL: http://codereview.chromium.org/993006

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@42067 0039d316-1c4b-4281-b951-d872f2087c98

4 files changed, 273 insertions, 63 deletions

diff --git a/chrome/common/extensions/api/extension_api.json b/chrome/common/extensions/api/extension_api.json
index 8925e81..b354018 100755
--- a/chrome/common/extensions/api/extension_api.json
+++ b/chrome/common/extensions/api/extension_api.json
@@ -925,24 +925,24 @@
       {
         "name": "executeScript",
         "type": "function",
-        "description": "",
+        "description": "Injects JavaScript code into a page. For details, see the <a href='content_scripts.html#pi'>programmatic injection</a> section of the content scripts doc.",
         "parameters": [
-          {"type": "integer", "name": "tabId", "optional": true, "description": "The id of tab which run the script, default to selected tab of current window."},
+          {"type": "integer", "name": "tabId", "optional": true, "description": "The ID of the tab in which to run the script; defaults to the selected tab of the current window."},
           {
             "type": "object",
             "name": "details",
-            "description": "Details of the script to run. Either the code or file property must be set, but both may not be set at the same time.",
+            "description": "Details of the script to run. Either the code or the file property must be set, but both may not be set at the same time.",
             "properties": {
               "code": {"type": "string", "optional": true, "description": "JavaScript code to execute."},
               "file": {"type": "string", "optional": true, "description": "JavaScript file to execute."},
-              "allFrames": {"type": "boolean", "optional": true, "description": "If allFrames is true, this function injects script into all frames of current page. By default, it's false and only inject script into top main frame."}
+              "allFrames": {"type": "boolean", "optional": true, "description": "If allFrames is true, this function injects script into all frames of current page. By default, it's false and script is injected only into the top main frame."}
             }
           },
           {
             "type": "function",
             "name": "callback",
             "optional": true,
-            "description": "When all scripts are executed, this callback is called.",
+            "description": "Called after all the JavaScript has been executed.",
             "parameters": []
           }
         ]
@@ -950,24 +950,24 @@
       {
         "name": "insertCSS",
         "type": "function",
-        "description": "",
+        "description": "Injects CSS into a page. For details, see the <a href='content_scripts.html#pi'>programmatic injection</a> section of the content scripts doc.",
         "parameters": [
-          {"type": "integer", "name": "tabId", "optional": true, "description": "The id of tab which run the script, default to selected tab of current window."},
+          {"type": "integer", "name": "tabId", "optional": true, "description": "The ID of the tab in which to insert the CSS; defaults to the selected tab of the current window."},
           {
             "type": "object",
             "name": "details",
-            "description": "Details of the css text to insert. Either the code or file property must be set, but both may not be set at the same time.",
+            "description": "Details of the CSS text to insert. Either the code or the file property must be set, but both may not be set at the same time.",
             "properties": {
               "code": {"type": "string", "optional": true, "description": "CSS code to be injected."},
               "file": {"type": "string", "optional": true, "description": "CSS file to be injected."},
-              "allFrames": {"type": "boolean", "optional": true, "description": "If allFrames is true, this function injects css text into all frames of current page. By default, it's false and only inject css text into top main frame."}
+              "allFrames": {"type": "boolean", "optional": true, "description": "If allFrames is true, this function injects CSS text into all frames of current page. By default, it's false and CSS is injected only into the top main frame."}
             }
           },
           {
             "type": "function",
             "name": "callback",
             "optional": true,
-            "description": "When all css are inserted, this callback is called.",
+            "description": "Called when all the CSS has been inserted.",
             "parameters": []
           }
         ]
diff --git a/chrome/common/extensions/docs/content_scripts.html b/chrome/common/extensions/docs/content_scripts.html
index e04229e..d358ab8 100644
--- a/chrome/common/extensions/docs/content_scripts.html
+++ b/chrome/common/extensions/docs/content_scripts.html
@@ -206,6 +206,13 @@
                 </li>
               </ol>
             </li><li>
+              <a href="#pi">Programmatic injection</a>
+              <ol>
+                <li style="display: none; ">
+                  <a>h3Name</a>
+                </li>
+              </ol>
+            </li><li>
               <a href="#execution-environment">Execution environment</a>
               <ol>
                 <li style="display: none; ">
@@ -351,9 +358,14 @@ learn about the
 
 <h2 id="registration">Manifest</h2>
 
-<p>Content scripts are registered in an extension's <a href="manifest.html">manifest.json</a> file, like so:
+<p>If your content script's code should always be injected,
+register it in the
+<a href="manifest.html">extension manifest</a>
+using the <code>content_scripts</code> field,
+as in the following example.
+</p>
 
-</p><pre>{
+<pre>{
   "name": "My extension",
   ...
   <b>"content_scripts": [
@@ -366,9 +378,28 @@ learn about the
   ...
 }</pre>
 
-<p>An extension can contain any number of content scripts, and a content script can consist of any number of JavaScript or CSS files. The value of the <code>matches</code> property controls when the content script will run.
+<p>
+If you want to inject the code only sometimes,
+use the
+<a href="manifest.html#permissions"><code>permissions</code></a> field instead,
+as described in <a href="#pi">Programmatic injection</a>.
+</p>
 
-</p><p>Each content script registered in the manifest can specify the following properties:</p>
+<pre>{
+  "name": "My extension",
+  ...
+  <b>"permissions": [
+    "tabs", "http://www.google.com/*"
+  ]</b>,
+  ...
+}</pre>
+
+<p>
+Using the <code>content_scripts</code> field,
+an extension can insert multiple content scripts into a page;
+each of these content scripts can have multiple JavaScript and CSS files.
+Each item in the <code>content_scripts</code> array
+can have the following properties:</p>
 
 <table>
   <tbody><tr>
@@ -377,7 +408,7 @@ learn about the
     <th>Description</th>
   </tr>
   <tr>
-    <td>matches</td>
+    <td><code>matches</code></td>
     <td>array of strings</td>
     <td><em>Required.</em>
     Controls the pages this content script will be injected into.
@@ -385,42 +416,42 @@ learn about the
     for more details on the syntax of these strings.</td>
   </tr>
   <tr>
-    <td>js</td>
-    <td><nobr>array of strings</nobr></td>
+    <td><code>css<code></code></code></td>
+    <td>array of strings</td>
     <td><em>Optional.</em>
-    The list of JavaScript files to be injected into matching pages. These are injected in the order they appear in this array.</td>
+    The list of CSS files to be injected into matching pages. These are injected in the order they appear in this array, before any DOM is constructed or displayed for the page.</td>
   </tr>
   <tr>
-    <td>css</td>
-    <td>array of strings</td>
+    <td><code>js<code></code></code></td>
+    <td><nobr>array of strings</nobr></td>
     <td><em>Optional.</em>
-    The list of CSS files to be injected into matching pages. These are injected in the order they appear in this array, before any DOM is constructed or displayed for the page.</td>
+    The list of JavaScript files to be injected into matching pages. These are injected in the order they appear in this array.</td>
   </tr>
   <tr>
-    <td>run_at</td>
+    <td><code>run_at<code></code></code></td>
     <td>string</td>
     <td><em>Optional.</em>
-    Controls when the files in <code>js</code> are injected. Can be <code>"document_start"</code>, <code>"document_end"</code>, or <code>"document_idle"</code>. Defaults to <code>"document_idle"</code>.
+    Controls when the files in <code>js</code> are injected. Can be "document_start", "document_end", or "document_idle". Defaults to "document_idle".
 
     <br><br>
 
-    In the case of <code>"document_start"</code>, the files are injected after any files from <code>"css"</code>, but before any other DOM is constructed or any other script is run.
+    In the case of "document_start", the files are injected after any files from <code>css</code>, but before any other DOM is constructed or any other script is run.
 
     <br><br>
 
-    In the case of <code>"document_end"</code>, the files are injected immediately after the DOM is complete, but before subresources like images and frames have loaded.
+    In the case of "document_end", the files are injected immediately after the DOM is complete, but before subresources like images and frames have loaded.
 
     <br><br>
 
-    In the case of <code>"document_idle"</code>, the browser chooses a time to inject scripts between <code>"document_end"</code> and immediately after the <code><a href="http://www.whatwg.org/specs/web-apps/current-work/#handler-onload">window.onload</a></code> event fires. The exact moment of injection depends on how complex the document is and how long it is taking to load, and is optimized for page load speed.
+    In the case of "document_idle", the browser chooses a time to inject scripts between "document_end" and immediately after the <code><a href="http://www.whatwg.org/specs/web-apps/current-work/#handler-onload">window.onload</a></code> event fires. The exact moment of injection depends on how complex the document is and how long it is taking to load, and is optimized for page load speed.
 
     <br><br>
 
-    <b>NOTE:</b> In <code>document_idle</code>, content scripts may not necessarily receive the window.onload event, because they may run after it has
-    already fired. In most cases, listening for the onload event is unnecessary for content scripts running at <code>document_idle</code> because they are guaranteed to run after the DOM is complete. If your script definitely needs to run after <code>window.onload</code> you can check if it has already fired by using the <code><a href="http://www.whatwg.org/specs/web-apps/current-work/#dom-document-readystate">document.readyState</a></code> property.</td>
+    <b>Note:</b> With "document_idle", content scripts may not necessarily receive the <code>window.onload</code> event, because they may run after it has
+    already fired. In most cases, listening for the <code>onload</code> event is unnecessary for content scripts running at "document_idle" because they are guaranteed to run after the DOM is complete. If your script definitely needs to run after <code>window.onload</code>, you can check if <code>onload</code> has already fired by using the <code><a href="http://www.whatwg.org/specs/web-apps/current-work/#dom-document-readystate">document.readyState</a></code> property.</td>
   </tr>
   <tr>
-    <td>all_frames</td>
+    <td><code>all_frames<code></code></code></td>
     <td>boolean</td>
     <td><em>Optional.</em>
     Controls whether the content script runs in all frames of the matching page, or only the top frame.
@@ -429,6 +460,74 @@ learn about the
   </tr>
 </tbody></table>
 
+<h2 id="pi">Programmatic injection</h2>
+
+<p>
+Inserting code into a page programmatically is useful
+when your JavaScript or CSS code
+shouldn't be injected into every single page
+that matches the pattern —
+for example, if you want a script to run
+only when the user clicks a browser action's icon.
+</p>
+
+<p>
+To insert code into a page,
+your extension must have
+<a href="xhr.html#requesting-permission">cross-origin permissions</a>
+for the page.
+It also must be able to use the <code>chrome.tabs</code> module.
+You can get both kinds of permission
+using the manifest file's
+<a href="manifest.html#permissions">permissions</a> field.
+</p>
+
+<p>
+Once you have permissions set up,
+you can inject JavaScript into a page by calling
+<a href="tabs.html#method-executeScript"><code>executeScript()</code></a>.
+To inject CSS, use
+<a href="tabs.html#method-insertCSS"><code>insertCSS()</code></a>.
+</p>
+
+<p>
+The following code
+(from the
+<a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extensions/docs/examples/api/browserAction/make_page_red/">make_page_red</a> example)
+reacts to a user click
+by inserting JavaScript into the current tab's page
+and executing the script.
+</p>
+
+<pre><em>/* in background.html */</em>
+chrome.browserAction.onClicked.addListener(function(tab) {
+  chrome.tabs.executeScript(null,
+                           {code:"document.body.bgColor='red'"});
+});
+
+<em>/* in manifest.json */</em>
+"permissions": [
+  "tabs", "http://*/*"
+],
+</pre>
+
+<p>
+When the browser is displaying an HTTP page
+and the user clicks this extension's browser action,
+the extension sets the page's <code>bgcolor</code> property to 'red'.
+The result,
+unless the page has CSS that sets the background color,
+is that the page turns red.
+</p>
+
+<p>
+Usually, instead of inserting code directly (as in the previous sample),
+you put the code in a file.
+You inject the file's contents like this:
+</p>
+
+<pre>chrome.tabs.executeScript(null, {file: "content_script.js"});</pre>
+
 
 <h2 id="execution-environment">Execution environment</h2>
 
@@ -568,6 +667,17 @@ cross-site requests for its content script.
 You can find other simple examples of communication via messages in the
 <a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extensions/docs/examples/api/messaging/">examples/api/messaging</a>
 directory.
+</p>
+
+<p>
+See
+<a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extensions/docs/examples/api/browserAction/make_page_red/">make_page_red</a> and
+<a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extensions/docs/examples/extensions/email_this_page/">email_this_page</a>
+for examples of programmatic injection.
+
+</p>
+
+<p>
 For more examples and for help in viewing the source code, see
 <a href="samples.html">Samples</a>.
 </p>
diff --git a/chrome/common/extensions/docs/static/content_scripts.html b/chrome/common/extensions/docs/static/content_scripts.html
index 2a57220..8071f3f 100644
--- a/chrome/common/extensions/docs/static/content_scripts.html
+++ b/chrome/common/extensions/docs/static/content_scripts.html
@@ -59,7 +59,12 @@ learn about the
 
 <h2 id="registration">Manifest</h2>
 
-<p>Content scripts are registered in an extension's <a href="manifest.html">manifest.json</a> file, like so:
+<p>If your content script's code should always be injected,
+register it in the
+<a href="manifest.html">extension manifest</a>
+using the <code>content_scripts</code> field,
+as in the following example.
+</p>
 
 <pre>{
   "name": "My extension",
@@ -74,9 +79,28 @@ learn about the
   ...
 }</pre>
 
-<p>An extension can contain any number of content scripts, and a content script can consist of any number of JavaScript or CSS files. The value of the <code>matches</code> property controls when the content script will run.
+<p>
+If you want to inject the code only sometimes,
+use the
+<a href="manifest.html#permissions"><code>permissions</code></a> field instead,
+as described in <a href="#pi">Programmatic injection</a>.
+</p>
 
-<p>Each content script registered in the manifest can specify the following properties:</p>
+<pre>{
+  "name": "My extension",
+  ...
+  <b>"permissions": [
+    "tabs", "http://www.google.com/*"
+  ]</b>,
+  ...
+}</pre>
+
+<p>
+Using the <code>content_scripts</code> field,
+an extension can insert multiple content scripts into a page;
+each of these content scripts can have multiple JavaScript and CSS files.
+Each item in the <code>content_scripts</code> array
+can have the following properties:</p>
 
 <table>
   <tr>
@@ -85,7 +109,7 @@ learn about the
     <th>Description</th>
   </tr>
   <tr>
-    <td>matches</td>
+    <td><code>matches</code></td>
     <td>array of strings</td>
     <td><em>Required.</em>
     Controls the pages this content script will be injected into.
@@ -93,42 +117,42 @@ learn about the
     for more details on the syntax of these strings.</td>
   </tr>
   <tr>
-    <td>js</td>
-    <td><nobr>array of strings</nobr></td>
+    <td><code>css<code></td>
+    <td>array of strings</td>
     <td><em>Optional.</em>
-    The list of JavaScript files to be injected into matching pages. These are injected in the order they appear in this array.</td>
+    The list of CSS files to be injected into matching pages. These are injected in the order they appear in this array, before any DOM is constructed or displayed for the page.</td>
   </tr>
   <tr>
-    <td>css</td>
-    <td>array of strings</td>
+    <td><code>js<code></td>
+    <td><nobr>array of strings</nobr></td>
     <td><em>Optional.</em>
-    The list of CSS files to be injected into matching pages. These are injected in the order they appear in this array, before any DOM is constructed or displayed for the page.</td>
+    The list of JavaScript files to be injected into matching pages. These are injected in the order they appear in this array.</td>
   </tr>
   <tr>
-    <td>run_at</td>
+    <td><code>run_at<code></td>
     <td>string</td>
     <td><em>Optional.</em>
-    Controls when the files in <code>js</code> are injected. Can be <code>"document_start"</code>, <code>"document_end"</code>, or <code>"document_idle"</code>. Defaults to <code>"document_idle"</code>.
+    Controls when the files in <code>js</code> are injected. Can be "document_start", "document_end", or "document_idle". Defaults to "document_idle".
 
     <br><br>
 
-    In the case of <code>"document_start"</code>, the files are injected after any files from <code>"css"</code>, but before any other DOM is constructed or any other script is run.
+    In the case of "document_start", the files are injected after any files from <code>css</code>, but before any other DOM is constructed or any other script is run.
 
     <br><br>
 
-    In the case of <code>"document_end"</code>, the files are injected immediately after the DOM is complete, but before subresources like images and frames have loaded.
+    In the case of "document_end", the files are injected immediately after the DOM is complete, but before subresources like images and frames have loaded.
 
     <br><br>
 
-    In the case of <code>"document_idle"</code>, the browser chooses a time to inject scripts between <code>"document_end"</code> and immediately after the <code><a href="http://www.whatwg.org/specs/web-apps/current-work/#handler-onload">window.onload</a></code> event fires. The exact moment of injection depends on how complex the document is and how long it is taking to load, and is optimized for page load speed.
+    In the case of "document_idle", the browser chooses a time to inject scripts between "document_end" and immediately after the <code><a href="http://www.whatwg.org/specs/web-apps/current-work/#handler-onload">window.onload</a></code> event fires. The exact moment of injection depends on how complex the document is and how long it is taking to load, and is optimized for page load speed.
 
     <br><br>
 
-    <b>NOTE:</b> In <code>document_idle</code>, content scripts may not necessarily receive the window.onload event, because they may run after it has
-    already fired. In most cases, listening for the onload event is unnecessary for content scripts running at <code>document_idle</code> because they are guaranteed to run after the DOM is complete. If your script definitely needs to run after <code>window.onload</code> you can check if it has already fired by using the <code><a href="http://www.whatwg.org/specs/web-apps/current-work/#dom-document-readystate">document.readyState</a></code> property.</td>
+    <b>Note:</b> With "document_idle", content scripts may not necessarily receive the <code>window.onload</code> event, because they may run after it has
+    already fired. In most cases, listening for the <code>onload</code> event is unnecessary for content scripts running at "document_idle" because they are guaranteed to run after the DOM is complete. If your script definitely needs to run after <code>window.onload</code>, you can check if <code>onload</code> has already fired by using the <code><a href="http://www.whatwg.org/specs/web-apps/current-work/#dom-document-readystate">document.readyState</a></code> property.</td>
   </tr>
   <tr>
-    <td>all_frames</td>
+    <td><code>all_frames<code></td>
     <td>boolean</td>
     <td><em>Optional.</em>
     Controls whether the content script runs in all frames of the matching page, or only the top frame.
@@ -137,6 +161,75 @@ learn about the
   </tr>
 </table>
 
+<h2 id="pi">Programmatic injection</h2>
+
+<p>
+Inserting code into a page programmatically is useful
+when your JavaScript or CSS code
+shouldn't be injected into every single page
+that matches the pattern &mdash;
+for example, if you want a script to run
+only when the user clicks a browser action's icon.
+</p>
+
+<p>
+To insert code into a page,
+your extension must have
+<a href="xhr.html#requesting-permission">cross-origin permissions</a>
+for the page.
+It also must be able to use the <code>chrome.tabs</code> module.
+You can get both kinds of permission
+using the manifest file's
+<a href="manifest.html#permissions">permissions</a> field.
+</p>
+
+<p>
+Once you have permissions set up,
+you can inject JavaScript into a page by calling
+<a href="tabs.html#method-executeScript"><code>executeScript()</code></a>.
+To inject CSS, use
+<a href="tabs.html#method-insertCSS"><code>insertCSS()</code></a>.
+</p>
+
+<p>
+The following code
+(from the
+<a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extensions/docs/examples/api/browserAction/make_page_red/">make_page_red</a> example)
+reacts to a user click
+by inserting JavaScript into the current tab's page
+and executing the script.
+</p>
+
+<pre>
+<em>/* in background.html */</em>
+chrome.browserAction.onClicked.addListener(function(tab) {
+  chrome.tabs.executeScript(null,
+                           {code:"document.body.bgColor='red'"});
+});
+
+<em>/* in manifest.json */</em>
+"permissions": [
+  "tabs", "http://*/*"
+],
+</pre>
+
+<p>
+When the browser is displaying an HTTP page
+and the user clicks this extension's browser action,
+the extension sets the page's <code>bgcolor</code> property to 'red'.
+The result,
+unless the page has CSS that sets the background color,
+is that the page turns red.
+</p>
+
+<p>
+Usually, instead of inserting code directly (as in the previous sample),
+you put the code in a file.
+You inject the file's contents like this:
+</p>
+
+<pre>chrome.tabs.executeScript(null, {file: "content_script.js"});</pre>
+
 
 <h2 id="execution-environment">Execution environment</h2>
 
@@ -280,6 +373,17 @@ cross-site requests for its content script.
 You can find other simple examples of communication via messages in the
 <a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extensions/docs/examples/api/messaging/">examples/api/messaging</a>
 directory.
+</p>
+
+<p>
+See
+<a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extensions/docs/examples/api/browserAction/make_page_red/">make_page_red</a> and
+<a href="http://src.chromium.org/viewvc/chrome/trunk/src/chrome/common/extensions/docs/examples/extensions/email_this_page/">email_this_page</a>
+for examples of programmatic injection.
+
+</p>
+
+<p>
 For more examples and for help in viewing the source code, see
 <a href="samples.html">Samples</a>.
 </p>
diff --git a/chrome/common/extensions/docs/tabs.html b/chrome/common/extensions/docs/tabs.html
index 54f5348..1ffabe3 100644
--- a/chrome/common/extensions/docs/tabs.html
+++ b/chrome/common/extensions/docs/tabs.html
@@ -1282,10 +1282,8 @@ For other examples and for help in viewing the source code, see
                       <var><span>callback</span></var></span>)</div>
 
               <div class="description">
-                <p class="todo">Undocumented.</p>
-                <p style="display: none; ">
-                  A description from the json schema def of the function goes here.
-                </p>
+                <p class="todo" style="display: none; ">Undocumented.</p>
+                <p>Injects JavaScript code into a page. For details, see the <a href="content_scripts.html#pi">programmatic injection</a> section of the content scripts doc.</p>
 
                 <!-- PARAMETERS -->
                 <h4>Parameters</h4>
@@ -1319,7 +1317,7 @@ For other examples and for help in viewing the source code, see
           <dd class="todo" style="display: none; ">
             Undocumented.
           </dd>
-          <dd>The id of tab which run the script, default to selected tab of current window.</dd>
+          <dd>The ID of the tab in which to run the script; defaults to the selected tab of the current window.</dd>
 
           <!-- OBJECT PROPERTIES -->
           <dd style="display: none; ">
@@ -1360,7 +1358,7 @@ For other examples and for help in viewing the source code, see
           <dd class="todo" style="display: none; ">
             Undocumented.
           </dd>
-          <dd>Details of the script to run. Either the code or file property must be set, but both may not be set at the same time.</dd>
+          <dd>Details of the script to run. Either the code or the file property must be set, but both may not be set at the same time.</dd>
 
           <!-- OBJECT PROPERTIES -->
           <dd>
@@ -1476,7 +1474,7 @@ For other examples and for help in viewing the source code, see
           <dd class="todo" style="display: none; ">
             Undocumented.
           </dd>
-          <dd>If allFrames is true, this function injects script into all frames of current page. By default, it's false and only inject script into top main frame.</dd>
+          <dd>If allFrames is true, this function injects script into all frames of current page. By default, it's false and script is injected only into the top main frame.</dd>
 
           <!-- OBJECT PROPERTIES -->
           <dd style="display: none; ">
@@ -1521,7 +1519,7 @@ For other examples and for help in viewing the source code, see
           <dd class="todo" style="display: none; ">
             Undocumented.
           </dd>
-          <dd>When all scripts are executed, this callback is called.</dd>
+          <dd>Called after all the JavaScript has been executed.</dd>
 
           <!-- OBJECT PROPERTIES -->
           <dd style="display: none; ">
@@ -2132,10 +2130,8 @@ For other examples and for help in viewing the source code, see
                       <var><span>callback</span></var></span>)</div>
 
               <div class="description">
-                <p class="todo">Undocumented.</p>
-                <p style="display: none; ">
-                  A description from the json schema def of the function goes here.
-                </p>
+                <p class="todo" style="display: none; ">Undocumented.</p>
+                <p>Injects CSS into a page. For details, see the <a href="content_scripts.html#pi">programmatic injection</a> section of the content scripts doc.</p>
 
                 <!-- PARAMETERS -->
                 <h4>Parameters</h4>
@@ -2169,7 +2165,7 @@ For other examples and for help in viewing the source code, see
           <dd class="todo" style="display: none; ">
             Undocumented.
           </dd>
-          <dd>The id of tab which run the script, default to selected tab of current window.</dd>
+          <dd>The ID of the tab in which to insert the CSS; defaults to the selected tab of the current window.</dd>
 
           <!-- OBJECT PROPERTIES -->
           <dd style="display: none; ">
@@ -2210,7 +2206,7 @@ For other examples and for help in viewing the source code, see
           <dd class="todo" style="display: none; ">
             Undocumented.
           </dd>
-          <dd>Details of the css text to insert. Either the code or file property must be set, but both may not be set at the same time.</dd>
+          <dd>Details of the CSS text to insert. Either the code or the file property must be set, but both may not be set at the same time.</dd>
 
           <!-- OBJECT PROPERTIES -->
           <dd>
@@ -2326,7 +2322,7 @@ For other examples and for help in viewing the source code, see
           <dd class="todo" style="display: none; ">
             Undocumented.
           </dd>
-          <dd>If allFrames is true, this function injects css text into all frames of current page. By default, it's false and only inject css text into top main frame.</dd>
+          <dd>If allFrames is true, this function injects CSS text into all frames of current page. By default, it's false and CSS is injected only into the top main frame.</dd>
 
           <!-- OBJECT PROPERTIES -->
           <dd style="display: none; ">
@@ -2371,7 +2367,7 @@ For other examples and for help in viewing the source code, see
           <dd class="todo" style="display: none; ">
             Undocumented.
           </dd>
-          <dd>When all css are inserted, this callback is called.</dd>
+          <dd>Called when all the CSS has been inserted.</dd>
 
           <!-- OBJECT PROPERTIES -->
           <dd style="display: none; ">