Move the `privacy` extension API out of experimental.

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

Index: chrome/common/extensions/docs/static/privacy.html
diff --git a/chrome/common/extensions/docs/static/privacy.html b/chrome/common/extensions/docs/static/privacy.html
new file mode 100644
index 0000000000000000000000000000000000000000..3b8696ef8e674b2750b5527fad0dcff095b30aaf
--- /dev/null
+++ b/chrome/common/extensions/docs/static/privacy.html
@@ -0,0 +1,73 @@
+<div id="pageData-name" class="pageData">Privacy</div>
+
+<!-- BEGIN AUTHORED CONTENT -->
+<p id="classSummary">
+  Use the <code>chrome.privacy</code> module to control usage of the features in
+  Chrome that can affect a user's privacy. This module relies on the
+  <a href="types.html#ChromeSetting">ChromeSetting prototype of the type API</a>
+  for getting and setting Chrome's configuration.
+</p>
+
+<p class="note">
+  The <a href="http://www.google.com/intl/en/landing/chrome/google-chrome-privacy-whitepaper.pdf">Chrome Privacy Whitepaper</a>
+  gives background detail regarding the features which this API can control.

[mkearney, 2012/01/19 23:48:25]

This doc doesn't cover all the features - is it worth softening this sentence a
little bit or is that overkill?

The Chrome Privacy Whitepaper describes in detail many of the features which
this API can control.

[Mike West, 2012/01/20 11:12:20]

There's a new version of the whitepaper in legal/PR/etc. review right now that
does/should cover all the features in this API. I'll send you a link via email
if you're curious.

+</p>
+
+<h2 id="manifest">Manifest</h2>
+<p>
+  You must declare the "privacy" permission in your extension's
+  <a href="manifest.html"> manifest</a> to use the API. For example:
+</p>
+
+<pre>{
+  "name": "My extension",
+  ...
+  <b>"permissions": [
+    "privacy"
+  ]</b>,
+  ...
+}</pre>
+
+<h2 id="usage">Usage</h2>
+
+<p>
+  Reading the current value of a setting is straightforward. You'll first need
+  to find the property you're interested in, then you'll call <code>get()</code>

[mkearney, 2012/01/19 23:48:25]

Small - can we add a Chrome here: 'current value of a Chrome setting'?

[Mike West, 2012/01/20 11:12:20]

Done.

+  on that object in order to retrieve it's current value and your extension's
+  level of control. For example, to determine if Chrome's Autofill feature is
+  enabled, you'd write:
+</p>
+
+<pre>chrome.privacy.services.autofillEnabled.get({}, function(details) {
+  if (details.value)
+    console.log('Autofill is on!');
+  else
+    console.log('Autofill is off!');
+});</pre>
+
+<p>
+  Changing the value of a setting is a little bit more complex, simply because
+  you first must verify that your extension can control the setting. If the
+  setting has been locked down by enterprise policy, or already been set by

[mkearney, 2012/01/19 23:48:25]

Small grammar fix - 'already been set' is better as 'already set' or else you
could put the whole verbial phrase - 'has already been set'.

[Mike West, 2012/01/20 11:12:20]

I don't like the way that sounds, honestly. I think of it as "If the setting has
(been locked down by enterprise policy), or (already been set by ...)." The verb
seems essential on both sides of the "or".

I'll just rewrite the section until we're both happy. It could use more detail
anyway.

+  another extension, then your extension will be denied write access. You'll
+  use the <code>get()</code> method to determine your level of access, and then
+  call <code>set()</code> if your extension can grab control over the setting:
+</p>

[mkearney, 2012/01/19 23:48:25]

Question: does one extension have more control over a setting than another
extension or is it first come first serve? Might be worth clarifying this. Also,
it seems a bit fuzzy to me that any one extension might have control over these
settings without some sort of pecking order, especially third-party extensions.

[Mike West, 2012/01/20 11:12:20]

The pecking order is well-defined by the Content Settings API. It boils down to
first-come-first-served, with the caveat that a more recently installed
extension can grab control. This, I think, makes intuitive sense. If I install
Privacy Protector, and then install Privacy Protector Plus Plus, I'd expect the
latter's setting to take hold. I'll add some documentation around what an
extension's options are in that scenario, and link off to the appropriate
section of the documentation.

+
+<pre>chrome.privacy.services.autofillEnabled.get({}, function(details) {
+  if (details.levelOfControl === 'controllable_by_this_extension') {
+    chrome.privacy.services.autofillEnabled.set({ value: true }, function() {
+      if (chrome.extension.lastError === undefined)
+        console.log("Hooray, it worked!");
+      else
+        console.log("Sadness!", chrome.extension.lastError);
+    }
+  }
+});</pre>
+
+<h2 id="examples">Examples</h2>
+<p>
+  For example code, see the
+  <a href="samples.html#privacy">Privacy API samples</a>.
+</p>
+<!-- END AUTHORED CONTENT -->