Updated preferences and proxy settings API documentation

BUG=no TEST=no Review URL: http://codereview.chromium.org/7067024 git-svn-id: svn://svn.chromium.org/chrome/trunk/src@86674 0039d316-1c4b-4281-b951-d872f2087c98

Updated preferences and proxy settings API documentation
BUG=no TEST=no Review URL: http://codereview.chromium.org/7067024 git-svn-id: svn://svn.chromium.org/chrome/trunk/src@86674 0039d316-1c4b-4281-b951-d872f2087c98
bc2bbd12 · battre@chromium.org · 692c534e · bc2bbd12 · bc2bbd12 · bc2bbd12
Commit bc2bbd12 authored May 25, 2011 by battre@chromium.org
4 changed files
--- a/chrome/common/extensions/docs/preferences.html
+++ b/chrome/common/extensions/docs/preferences.html
@@ -16,7 +16,7 @@
    <script type="text/javascript" src="js/api_page_generator.js"></script>
    <script type="text/javascript" src="js/bootstrap.js"></script>
    <script type="text/javascript" src="js/sidebar.js"></script>
-  <title>chrome.preferences - Google Chrome Extensions - Google Code</title></head>
+  <title>Preferences - Google Chrome Extensions - Google Code</title></head>
  <body>  <div id="gc-container" class="labs">
      <div id="devModeWarning">
        You are viewing extension docs in chrome via the 'file:' scheme: are you expecting to see local changes when you refresh? You'll need run chrome with --allow-file-access-from-files.
@@ -251,16 +251,23 @@
    <div class="g-unit" id="gc-pagecontent">
      <div id="pageTitle">
-        <h1 class="page_title">chrome.preferences</h1>
+        <h1 class="page_title">Preferences</h1>
      </div>
        <!-- TABLE OF CONTENTS -->
        <div id="toc">
          <h2>Contents</h2>
          <ol>
-            <li style="display: none; ">
+            <li>
-              <a>h2Name</a>
+              <a href="#description">Overview</a>
              <ol>
-                <li>
+                <li style="display: none; ">
+                  <a>h3Name</a>
+                </li>
+              </ol>
+            </li><li>
+              <a href="#precedence">Precedence</a>
+              <ol>
+                <li style="display: none; ">
                  <a>h3Name</a>
                </li>
              </ol>
@@ -312,7 +319,96 @@
        </p>
        <!-- STATIC CONTENT PLACEHOLDER -->
-        <div id="static"></div>
+        <div id="static"><div id="pageData-name" class="pageData">Preferences</div>
+<!-- BEGIN AUTHORED CONTENT -->
+<p id="classSummary">
+The <code>chrome.preferences</code> module contains a prototype for giving other
+modules access to manage preferences stored by Chrome. This prototype is used,
+for example, for <a href="proxy.html#property-settings"><code>chrome.proxy.settings</code></a>.
+</p>
+<h2 id="description">Overview</h2>
+<p>
+The preferences API provides a common set of functions
+(<code>get()</code>, <code>set()</code>, and <code>clear()</code>) as
+well as an event publisher (<code>onChange</code>) for various
+preferences in Chrome. The <a href="proxy.html#overview-examples">proxy settings
+ examples</a> demonstrate how these functions are intended to be used.
+</p>
+<!--
+<h2 id="lifecycle">Life cycle of preferences</h2>
+<p>
+The life cycle of preferences depends on whether they are set for regular or
+incognito profiles. </p>
+-->
+<p>
+Currently, preferences can only be set for regular profiles. Once set, they
+remain in place until they are cleared by the governing extension, or the
+governing extension is disabled or uninstalled.
+</p>
+<h2 id="precedence">Precedence</h2>
+<p>
+Chrome manages preferences on different layers. The following list describes the
+layers that may influence the effective preferences, in increasing order of
+precedence.
+</p><ol>
+  <li>System preferences provided by the operating system</li>
+  <li>Command-line parameters</li>
+  <li>Preferences set by extensions</li>
+  <li>Policies</li>
+</ol>
+<p></p>
+<p>
+As the list implies, policies might overrule any changes that you specify with
+your extension.
+</p>
+<!--
+<p>
+As discussed above, Chrome allows using different preferences for regular
+windows and incognito windows. The following example illustrates the behavior.
+Assume that no policy overrides the preferences and that an extension can set
+preferences for regular windows <b>(R)</b> and preferences for incognito windows
+<b>(I)</b>.
+</p>
+<p>
+<ul>
+  <li>If only <b>(R)</b> is set, these preferences are effective for both
+  regular and incognito windows.</li>
+  <li>If only <b>(I)</b> is set, these preferences are effective for only
+  incognito windows. Regular windows use the preferences determined by the lower
+  layers (command-line options and system settings).</li>
+  <li>If both <b>(R)</b> and <b>(I)</b> are set, the respective preferences are
+  used for regular and incognito windows.</li>
+</ul>
+</p>
+-->
+<p>
+If two or more extensions want to set the same preference to different values,
+the extension installed most recently takes precedence over the other
+extensions.
+<!-- If the
+extension installed last sets only <b>(I)</b>, the preference of regular windows
+can be defined by previously installed extensions. -->
+</p>
+<p>
+The <em>effective</em> preference value is the setting that results from
+considering the preference rules. It is used by Chrome.
+</p><p>
+<!-- END AUTHORED CONTENT -->
+</p></div>
        <!-- API PAGE -->
        <div class="apiPage">

--- a/chrome/common/extensions/docs/proxy.html
+++ b/chrome/common/extensions/docs/proxy.html
@@ -277,13 +277,6 @@
                  <a href="#bypass_list">Bypass list</a>
                </li>
              </ol>
-            </li><li>
-              <a href="#precedence">Precedence</a>
-              <ol>
-                <li style="display: none; ">
-                  <a>h3Name</a>
-                </li>
-              </ol>
            </li><li>
              <a href="#overview-examples">Examples</a>
              <ol>
@@ -350,7 +343,8 @@
 <!-- BEGIN AUTHORED CONTENT -->
 <p id="classSummary">
 Use the <code>chrome.proxy</code> module to manage Chrome's
-proxy settings.
+proxy settings. This module relies on the <a href="preferences.html">preferences
+  API</a> for getting and setting the proxy configuration.
 </p>
 <h2 id="manifest">Manifest</h2>
@@ -495,61 +489,13 @@ Individual servers may be excluded from being proxied with the
 </dl>
-<h2 id="precedence">Precedence</h2>
-<p>
-Chrome manages settings on different layers. The following list describes the
-layers that may influence the effective proxy settings, in increasing order of
-precedence.
-</p><ol>
-  <li>System settings provided by the operating system</li>
-  <li>Command line parameters</li>
-  <li>Preferences set by extensions</li>
-  <li>Policies</li>
-</ol>
-<p></p>
-<p>
-As the list implies, policies might overrule any changes that you specify with
-the proxy settings API.
-</p>
-<!--
-<p>
-Chrome allows using different proxy settings for regular windows and incognito
-windows. The following example illustrates the behavior. Assume that no policy
-overrides the proxy settings and that an extension can set proxy settings for
-regular windows <b>(R)</b> and proxy settings for incognito windows <b>(I)</b>.
-</p>
-<p>
-<ul>
-  <li>If only <b>(R)</b> is set, these settings are effective for both regular
-  and incognito windows.</li>
-  <li>If only <b>(I)</b> is set, these settings are effective for only incognito
-  windows. Regular windows use the proxy settings determined by the lower layers
-  (command-line options and system settings).</li>
-  <li>If both <b>(R)</b> and <b>(I)</b> are set, the respective settings are
-  used for regular and incognito windows.</li>
-</ul>
-</p>
-<p>
-If two extensions want to set proxy settings, the extension installed last takes
-precedence over the other extensions. If the extension installed last sets only
-<b>(I)</b>, the settings of regular windows can be defined by more recently
-installed extensions.
-</p>
-->
 <h2 id="overview-examples">Examples</h2>
 <p>
 The following code sets a SOCKS 5 proxy for HTTP connections to all servers but
 foobar.com and uses direct connections for all other protocols. The settings
-apply to regular and incognito windows.
+apply to regular and incognito windows, as incognito windows inherit preferences
+from regular windows. Please also consult the <a href="preferences.html">Preferences API</a> documentation.
 </p>
 <pre>var config = {
@@ -568,7 +514,7 @@ chrome.proxy.settings.set(
 </pre>
 <p>
-The following code sets a custom pac script.
+The following code sets a custom PAC script.
 </p>
 <pre>var config = {
@@ -587,7 +533,8 @@ chrome.proxy.settings.set(
 </pre>
 <p>
-The next snippet queries the current proxy settings.
+The next snippet queries the currently effective proxy settings. The effective
+proxy settings can be determined by another extension or by a policy. See the <a href="preferences.html">Preferences API</a> documentation for details.
 </p>
 <pre>chrome.proxy.settings.get(

--- a/chrome/common/extensions/docs/static/preferences.html
+++ b/chrome/common/extensions/docs/static/preferences.html
+<div id="pageData-name" class="pageData">Preferences</div>
+<!-- BEGIN AUTHORED CONTENT -->
+<p id="classSummary">
+The <code>chrome.preferences</code> module contains a prototype for giving other
+modules access to manage preferences stored by Chrome. This prototype is used,
+for example, for <a
+  href="proxy.html#property-settings"><code>chrome.proxy.settings</code></a>.
+</p>
+<h2 id="description">Overview</h2>
+<p>
+The preferences API provides a common set of functions
+(<code>get()</code>, <code>set()</code>, and <code>clear()</code>) as
+well as an event publisher (<code>onChange</code>) for various
+preferences in Chrome. The <a href="proxy.html#overview-examples">proxy settings
+ examples</a> demonstrate how these functions are intended to be used.
+</p>
+<!--
+<h2 id="lifecycle">Life cycle of preferences</h2>
+<p>
+The life cycle of preferences depends on whether they are set for regular or
+incognito profiles. </p>
+-->
+<p>
+Currently, preferences can only be set for regular profiles. Once set, they
+remain in place until they are cleared by the governing extension, or the
+governing extension is disabled or uninstalled.
+</p>
+<h2 id="precedence">Precedence</h2>
+<p>
+Chrome manages preferences on different layers. The following list describes the
+layers that may influence the effective preferences, in increasing order of
+precedence.
+<ol>
+  <li>System preferences provided by the operating system</li>
+  <li>Command-line parameters</li>
+  <li>Preferences set by extensions</li>
+  <li>Policies</li>
+</ol>
+</p>
+<p>
+As the list implies, policies might overrule any changes that you specify with
+your extension.
+</p>
+<!--
+<p>
+As discussed above, Chrome allows using different preferences for regular
+windows and incognito windows. The following example illustrates the behavior.
+Assume that no policy overrides the preferences and that an extension can set
+preferences for regular windows <b>(R)</b> and preferences for incognito windows
+<b>(I)</b>.
+</p>
+<p>
+<ul>
+  <li>If only <b>(R)</b> is set, these preferences are effective for both
+  regular and incognito windows.</li>
+  <li>If only <b>(I)</b> is set, these preferences are effective for only
+  incognito windows. Regular windows use the preferences determined by the lower
+  layers (command-line options and system settings).</li>
+  <li>If both <b>(R)</b> and <b>(I)</b> are set, the respective preferences are
+  used for regular and incognito windows.</li>
+</ul>
+</p>
+-->
+<p>
+If two or more extensions want to set the same preference to different values,
+the extension installed most recently takes precedence over the other
+extensions.
+<!-- If the
+extension installed last sets only <b>(I)</b>, the preference of regular windows
+can be defined by previously installed extensions. -->
+</p>
+<p>
+The <em>effective</em> preference value is the setting that results from
+considering the preference rules. It is used by Chrome.
+<p>
+<!-- END AUTHORED CONTENT -->
--- a/chrome/common/extensions/docs/static/proxy.html
+++ b/chrome/common/extensions/docs/static/proxy.html
@@ -3,7 +3,8 @@
 <!-- BEGIN AUTHORED CONTENT -->
 <p id="classSummary">
 Use the <code>chrome.proxy</code> module to manage Chrome's
-proxy settings.
+proxy settings. This module relies on the <a href="preferences.html">preferences
+  API</a> for getting and setting the proxy configuration.
 </p>
 <h2 id="manifest">Manifest</h2>
@@ -149,61 +150,14 @@ Individual servers may be excluded from being proxied with the
 </dl>
-<h2 id="precedence">Precedence</h2>
-<p>
-Chrome manages settings on different layers. The following list describes the
-layers that may influence the effective proxy settings, in increasing order of
-precedence.
-<ol>
-  <li>System settings provided by the operating system</li>
-  <li>Command line parameters</li>
-  <li>Preferences set by extensions</li>
-  <li>Policies</li>
-</ol>
-</p>
-<p>
-As the list implies, policies might overrule any changes that you specify with
-the proxy settings API.
-</p>
-<!--
-<p>
-Chrome allows using different proxy settings for regular windows and incognito
-windows. The following example illustrates the behavior. Assume that no policy
-overrides the proxy settings and that an extension can set proxy settings for
-regular windows <b>(R)</b> and proxy settings for incognito windows <b>(I)</b>.
-</p>
-<p>
-<ul>
-  <li>If only <b>(R)</b> is set, these settings are effective for both regular
-  and incognito windows.</li>
-  <li>If only <b>(I)</b> is set, these settings are effective for only incognito
-  windows. Regular windows use the proxy settings determined by the lower layers
-  (command-line options and system settings).</li>
-  <li>If both <b>(R)</b> and <b>(I)</b> are set, the respective settings are
-  used for regular and incognito windows.</li>
-</ul>
-</p>
-<p>
-If two extensions want to set proxy settings, the extension installed last takes
-precedence over the other extensions. If the extension installed last sets only
-<b>(I)</b>, the settings of regular windows can be defined by more recently
-installed extensions.
-</p>
-->
 <h2 id="overview-examples">Examples</h2>
 <p>
 The following code sets a SOCKS 5 proxy for HTTP connections to all servers but
 foobar.com and uses direct connections for all other protocols. The settings
-apply to regular and incognito windows.
+apply to regular and incognito windows, as incognito windows inherit preferences
+from regular windows. Please also consult the <a
+  href="preferences.html">Preferences API</a> documentation.
 </p>
 <pre>
@@ -223,7 +177,7 @@ chrome.proxy.settings.set(
 </pre>
 <p>
-The following code sets a custom pac script.
+The following code sets a custom PAC script.
 </p>
 <pre>
@@ -243,7 +197,9 @@ chrome.proxy.settings.set(
 </pre>
 <p>
-The next snippet queries the current proxy settings.
+The next snippet queries the currently effective proxy settings. The effective
+proxy settings can be determined by another extension or by a policy. See the <a
+  href="preferences.html">Preferences API</a> documentation for details.
 </p>
 <pre>