Updated preferences and proxy settings API documentation

Updated preferences and proxy settings API documentation


BUG=no
TEST=no

Committed: http://src.chromium.org/viewvc/chrome?view=rev&revision=86674

[battre, 2011-05-24 14:36:40]

As a consequence of the discussion of how the API should look like, this is a
new version of the documentation.

Kathy, I have uploaded this to the same location, I sent you before.

Please have a look.

Thanks,
Dominic

[Matt Perry, 2011-05-24 17:49:28]

LGTM

[kathyw, 2011-05-24 18:57:49]

Some tweaks, but it basically looks good.

http://codereview.chromium.org/7067024/diff/1/chrome/common/extensions/docs/s...
File chrome/common/extensions/docs/static/preferences.html (right):

http://codereview.chromium.org/7067024/diff/1/chrome/common/extensions/docs/s...
chrome/common/extensions/docs/static/preferences.html:6: modules access to
manage Chrome's preferences. This prototype is used for
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 :)

http://codereview.chromium.org/7067024/diff/1/chrome/common/extensions/docs/s...
chrome/common/extensions/docs/static/preferences.html:11: <h2
id="description">Functions</h2>
Functions -> Overview

(otherwise, this sounds like a reference section)

http://codereview.chromium.org/7067024/diff/1/chrome/common/extensions/docs/s...
chrome/common/extensions/docs/static/preferences.html:14: The preferences API
provides a commen set of functions
commen -> common

http://codereview.chromium.org/7067024/diff/1/chrome/common/extensions/docs/s...
chrome/common/extensions/docs/static/preferences.html:21: <h2
id="lifecycle">Life cycle of preferences</h2>
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.

http://codereview.chromium.org/7067024/diff/1/chrome/common/extensions/docs/s...
chrome/common/extensions/docs/static/preferences.html:25: incognito profiles.
Currently, preferences can only be set for regular profiles.
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&mdash;not for
incognito profiles.

http://codereview.chromium.org/7067024/diff/1/chrome/common/extensions/docs/s...
chrome/common/extensions/docs/static/preferences.html:29: Preferences for
<em>regular profiles</em> are persisted to disk. Once set, they
"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....

http://codereview.chromium.org/7067024/diff/1/chrome/common/extensions/docs/s...
chrome/common/extensions/docs/static/preferences.html:42: <li>Command line
parameters</li>
-> Command-line options

(to be consistent with phrasing later)

http://codereview.chromium.org/7067024/diff/1/chrome/common/extensions/docs/s...
chrome/common/extensions/docs/static/preferences.html:77: extension installed
last takes precedence over the other extensions.
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.)

http://codereview.chromium.org/7067024/diff/1/chrome/common/extensions/docs/s...
chrome/common/extensions/docs/static/preferences.html:77: extension installed
last takes precedence over the other extensions.
"two" -> "two or more"

(so that "other extensions" makes sense)

http://codereview.chromium.org/7067024/diff/1/chrome/common/extensions/docs/s...
File chrome/common/extensions/docs/static/proxy.html (right):

http://codereview.chromium.org/7067024/diff/1/chrome/common/extensions/docs/s...
chrome/common/extensions/docs/static/proxy.html:180: The following code sets a
custom pac script.
pac -> PAC

(to match other uses)

http://codereview.chromium.org/7067024/diff/1/chrome/common/extensions/docs/s...
chrome/common/extensions/docs/static/proxy.html:201: proxy settings can be
determined by another extension or by a policy, see the <a
, see ->
. See

documentation. -> 
documentation for details.

[battre, 2011-05-24 19:18:02]

Thanks a lot for the review.

http://codereview.chromium.org/7067024/diff/1/chrome/common/extensions/docs/s...
File chrome/common/extensions/docs/static/preferences.html (right):

http://codereview.chromium.org/7067024/diff/1/chrome/common/extensions/docs/s...
chrome/common/extensions/docs/static/preferences.html:6: modules access to
manage Chrome's preferences. This prototype is used for
On 2011/05/24 18:57:50, kathyw wrote:
> 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 :)

Done.

http://codereview.chromium.org/7067024/diff/1/chrome/common/extensions/docs/s...
chrome/common/extensions/docs/static/preferences.html:11: <h2
id="description">Functions</h2>
On 2011/05/24 18:57:50, kathyw wrote:
> Functions -> Overview
> 
> (otherwise, this sounds like a reference section)

Done.

http://codereview.chromium.org/7067024/diff/1/chrome/common/extensions/docs/s...
chrome/common/extensions/docs/static/preferences.html:14: The preferences API
provides a commen set of functions
On 2011/05/24 18:57:50, kathyw wrote:
> commen -> common

Done.

http://codereview.chromium.org/7067024/diff/1/chrome/common/extensions/docs/s...
chrome/common/extensions/docs/static/preferences.html:21: <h2
id="lifecycle">Life cycle of preferences</h2>
On 2011/05/24 18:57:50, kathyw wrote:
> 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.

Done.

http://codereview.chromium.org/7067024/diff/1/chrome/common/extensions/docs/s...
chrome/common/extensions/docs/static/preferences.html:25: incognito profiles.
Currently, preferences can only be set for regular profiles.
On 2011/05/24 18:57:50, kathyw wrote:
> 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&mdash;not for
> incognito profiles.

Done.

http://codereview.chromium.org/7067024/diff/1/chrome/common/extensions/docs/s...
chrome/common/extensions/docs/static/preferences.html:29: Preferences for
<em>regular profiles</em> are persisted to disk. Once set, they
On 2011/05/24 18:57:50, kathyw wrote:
> "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....

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

http://codereview.chromium.org/7067024/diff/1/chrome/common/extensions/docs/s...
chrome/common/extensions/docs/static/preferences.html:42: <li>Command line
parameters</li>
On 2011/05/24 18:57:50, kathyw wrote:
> -> Command-line options
> 
> (to be consistent with phrasing later)

Done.

http://codereview.chromium.org/7067024/diff/1/chrome/common/extensions/docs/s...
chrome/common/extensions/docs/static/preferences.html:77: extension installed
last takes precedence over the other extensions.
On 2011/05/24 18:57:50, kathyw wrote:
> 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.)

Done.

http://codereview.chromium.org/7067024/diff/1/chrome/common/extensions/docs/s...
chrome/common/extensions/docs/static/preferences.html:77: extension installed
last takes precedence over the other extensions.
On 2011/05/24 18:57:50, kathyw wrote:
> "two" -> "two or more"
> 
> (so that "other extensions" makes sense)

Done.

http://codereview.chromium.org/7067024/diff/1/chrome/common/extensions/docs/s...
File chrome/common/extensions/docs/static/proxy.html (right):

http://codereview.chromium.org/7067024/diff/1/chrome/common/extensions/docs/s...
chrome/common/extensions/docs/static/proxy.html:180: The following code sets a
custom pac script.
On 2011/05/24 18:57:50, kathyw wrote:
> pac -> PAC
> 
> (to match other uses)

Done.

http://codereview.chromium.org/7067024/diff/1/chrome/common/extensions/docs/s...
chrome/common/extensions/docs/static/proxy.html:201: proxy settings can be
determined by another extension or by a policy, see the <a
On 2011/05/24 18:57:50, kathyw wrote:
> , see ->
> . See
> 
> documentation. -> 
> documentation for details.

Done.

[kathyw, 2011-05-24 20:02:40]

LGTM

(I forgot to note a couple of commas before, but they aren't crucial.)

http://codereview.chromium.org/7067024/diff/5001/chrome/common/extensions/doc...
File chrome/common/extensions/docs/static/preferences.html (right):

http://codereview.chromium.org/7067024/diff/5001/chrome/common/extensions/doc...
chrome/common/extensions/docs/static/preferences.html:7: for example for <a
for example -> , for example,

[battre, 2011-05-24 20:22:57]

Done and made minor change (removed Effective from getEffective() and
onChangeEffective()) as per discussion in other CLs.

http://codereview.chromium.org/7067024/diff/5001/chrome/common/extensions/doc...
File chrome/common/extensions/docs/static/preferences.html (right):

http://codereview.chromium.org/7067024/diff/5001/chrome/common/extensions/doc...
chrome/common/extensions/docs/static/preferences.html:7: for example for <a
On 2011/05/24 20:02:40, kathyw wrote:
> for example -> , for example,

Done.

[kathyw, 2011-05-24 20:26:10]

LGTM

(still)

Thanks for adding those ,s...