Update documentation for "file_system_provider" manifest section.

chrome/common/extensions/docs/templates/intros/fileSystemProvider.html

 <h2 id="manifest">Manifest</h2>
-<p>You must declare the "fileSystemProvider" permission
+<p>You must declare the "fileSystemProvider" permission and section

[not at google - send to devlin, 2015/05/08 16:47:39]

Is "and" actually true here, or is it an "and/or" situation?

If the former, without questioning why, you should make the manifest key imply
requesting the permission (in fact, you could consider doing this anyway).

If the latter, you should briefly comment that in the manifest.json section.
People just cargo-cult code and if the sample is as you've written it, that's
what people will write.

Generally speaking for this documentation, it's unclear to me why I'd want to
specify the permission vs the manifest, and in fact what the manifest section
does. What you've got here is a bit improvement - at least it's *present* in the
documentation - but it'd be nice to see these things fleshed out.

Also, some issues in the docs I see generated in
https://chrome-apps-doc.appspot.com/_patch/1127273004/apps/fileSystemProvider


"""
The file_system_provider section must be declared as follows:

configurable (boolean) - required

Whether configuring via onConfigureRequested is supported.

multiple_mounts (boolean) - required

Whether multiple (more than one) mounted file systems are supported.

source (enum of "file", "device", or "network") - required

For file the source is a file passed via onLaunched event. For device contents
are fetched from an external device (eg. plugged via USB), without using
file_handlers. Finally, for device source, contents should be fetched via
network.
"""

Problems:
(a) I can't find this onConfigureRequested function, because it's nodoc. You
should un-nodoc it, and also, use $(ref:onConfigureRequested) so that it
generates a link.
(b) The onLaunched event is in runtime, so likewise use
$(ref:runtime.onLaunched).
(c) file/network/device should be "file"/"network"/"device"

[mtomasz, 2015/05/11 01:08:04]

It's currently optional, as I wanted to keep backward compatibility while
encouraging new developers to declare both. However, I guess it's OK to break
apps on dev, so let me make it mandatory in a follow up CL.
Permission is simply for the API. And the section specifies some extras. We do
the same for fileBrowserHandler API. Do you suggest to (1) automatically imply a
permission when "file_system_provider" section is present or (2) rename the
manifest section to something more meaningful, like
"file_system_provider_capabilities"/"provider_capabilities"?
Done. Merged both CLs.
Done.
Done.

[not at google - send to devlin, 2015/05/12 00:08:51]

manifest section to something more meaningful, like
"file_system_provider_capabilities"/"provider_capabilities"

looks like you did that? FWIW I would also have been ok with keeping it
"file_system_provider" and make that imply the "fileSystemProvider" permission;
you'd then document the permission as "implying the file_system_provider
manifest key with default values of <whatever>".

 in the <a href="manifest">extension manifest</a>
 to use the File System Provider API.
 For example:</p>
 <pre data-filename="manifest.json">
 {
   "name": "My extension",
   ...
-  <b>"permissions": [
+  "permissions": [
     "fileSystemProvider"
-  ]</b>,
+  ],
+  ...
+  "file_system_provider": [
+    "configurable": true,
+    "multiple_mounts": true,
+    "source": "network"
+  ],
   ...
 }
 </pre>
 
+<p class="api_reference">
+The <code>file_system_provider</code> section must be declared as follows:
+{{+partials.manifest_type
+   type:apis.extensions.manifestTypes.byName.FileSystemProviderCapabilities /}}
+</p>
+
 <h2 id="overview">Overview</h2>
 <p>
 File System Provider API allows extensions to support virtual file systems,
 which are available in the file manager on Chrome OS.
 Use cases include decompressing archives and accessing files in a cloud
 service other than Drive.
 </p>
 
 <h2 id="archives">File handlers</h2>
 <p>
@@ skipping 18 matching lines @@
 <a href="#method-unmount"> unmount</a> method.
 </p>
 <p>
 In case of acting as a file handler, the handled file may need to be stored
 to access it after either a reboot, or suspending and resuming an event page
 of the providing extension. In such case
 <a href="fileSystem#method-retainEntry">chrome.fileSystem.retainEntry</a> and
 <a href="fileSystem#method-restoreEntry">chrome.fileSystem.restoreEntry</a>
 should be used.
 </p>