Updated preferences and proxy settings API documentation

chrome/common/extensions/docs/static/preferences.html

Index: chrome/common/extensions/docs/static/preferences.html
diff --git a/chrome/common/extensions/docs/static/preferences.html b/chrome/common/extensions/docs/static/preferences.html
new file mode 100644
index 0000000000000000000000000000000000000000..db40f998f3978e57e93f60fa93892da0417e18ea
--- /dev/null
+++ b/chrome/common/extensions/docs/static/preferences.html
@@ -0,0 +1,88 @@
+<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 Chrome's preferences. This prototype is used for

[kathyw, 2011/05/24 18:57:50]

Chrome's preferences
 -> Chrome-related preferences
or maybe:
 -> preferences stored by Chrome

("Chrome's preferences" is unclear, plus it sounds like Chrome is a person :)

[battre, 2011/05/24 19:18:03]

Done.

+example for <a
+  href="proxy.html#property-settings"><code>chrome.proxy.settings</code></a>.
+</p>
+
+<h2 id="description">Functions</h2>

[kathyw, 2011/05/24 18:57:50]

Functions -> Overview

(otherwise, this sounds like a reference section)

[battre, 2011/05/24 19:18:03]

Done.

+
+<p>
+The preferences API provides a commen set of functions

[kathyw, 2011/05/24 18:57:50]

commen -> common

[battre, 2011/05/24 19:18:03]

Done.

+(<code>getEffective()</code>, <code>set()</code>, and <code>clear()</code>) as
+well as an event publisher (<code>onChangeEffective</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>

[kathyw, 2011/05/24 18:57:50]

Delete this heading? Until there's an incognito story, there's not much to say
here, and the overview's a fine place to say it.

[battre, 2011/05/24 19:18:03]

Done.

+
+<p>
+The life cycle of preferences depends on whether they are set for regular or
+incognito profiles. Currently, preferences can only be set for regular profiles.

[kathyw, 2011/05/24 18:57:50]

It seems weird to talk about incognito life cycles when there's no support (yet)
for incognito preferences. How about deleting the first sentence and changing
the second to:

Currently, preferences can be set for regular profiles only—not for
incognito profiles.

[battre, 2011/05/24 19:18:03]

Done.

+</p>
+
+<p>
+Preferences for <em>regular profiles</em> are persisted to disk. Once set, they

[kathyw, 2011/05/24 18:57:50]

"persisted to disk" sounds a little old fashioned to me, plus it seems a bit
redundant. How about changing this paragraph to be just 2 sentences (the
previous paragraph's sentence, plus the second one):

Currently, preferences...profiles. Once set, preferences remain in place....

[battre, 2011/05/24 19:18:03]

Done. I'd like to change it back to "Preferences for <em>regular profiles</em>
are persisted." once we have incognito preferences as well.

+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>

[kathyw, 2011/05/24 18:57:50]

-> Command-line options

(to be consistent with phrasing later)

[battre, 2011/05/24 19:18:03]

Done.

+  <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 extensions want to set the same preference to different values, the
+extension installed last takes precedence over the other extensions.

[kathyw, 2011/05/24 18:57:50]

extension installed last
 -> most recently installed extension

(I had to think to understand what "last" means -- perhaps because "last" can
also mean "previously". "most recently" seems clearer.)

[kathyw, 2011/05/24 18:57:50]

"two" -> "two or more"

(so that "other extensions" makes sense)

[battre, 2011/05/24 19:18:03]

Done.

[battre, 2011/05/24 19:18:03]

Done.

+<!-- 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 -->