Includes intro and generated API reference, updates to the 'manage data' doc, and added permission to manifest doc.

Review URL: https://codereview.chromium.org/12340059

git-svn-id: svn://svn.chromium.org/chrome/trunk/src@185277 0039d316-1c4b-4281-b951-d872f2087c98

5 files changed, 284 insertions, 34 deletions

diff --git a/chrome/common/extensions/api/sync_file_system.idl b/chrome/common/extensions/api/sync_file_system.idl
index 0689b0e..dcc3011 100644
--- a/chrome/common/extensions/api/sync_file_system.idl
+++ b/chrome/common/extensions/api/sync_file_system.idl
@@ -49,17 +49,28 @@ namespace syncFileSystem {
   };
 
   dictionary FileInfo {
-    // |fileEntry| will contain name and path information of synchronized file.
-    // On file deletion, fileEntry information will still be available but file
-    // will no longer exist.
+    // <code>fileEntry</code> for the target file whose status has changed.
+    // Contains name and path information of synchronized file.
+    // On file deletion,
+    // <code>fileEntry</code> information will still be available
+    // but file will no longer exist.
     [instanceOf=FileEntry] object fileEntry;
     
+    // Resulting file status after $ref:onFileStatusChanged event.
+    // The status value can be <code>'synced'</code>, 
+    // <code>'pending'</code> or <code>'conflicting'</code>.
     FileStatus status;
     
-    // Only applies if status is synced.
+    // Sync action taken to fire $ref:onFileStatusChanged event.
+    // The action value can be
+    // <code>'added'</code>, <code>'updated'</code> or <code>'deleted'</code>.
+    // Only applies if status is <code>'synced'</code>.
     SyncAction? action;
     
-    // Only applies if status is synced.
+    // Sync direction for the $ref:onFileStatusChanged event.
+    // Sync direction value can be
+    // <code>'local_to_remote'</code> or <code>'remote_to_local'</code>.
+    // Only applies if status is <code>'synced'</code>.
     SyncDirection? direction;
   };
 
@@ -73,28 +84,30 @@ namespace syncFileSystem {
     DOMString description;
   };
 
-  // [nodoc] A callback type for requestFileSystem.
+  // A callback type for requestFileSystem.
   callback GetFileSystemCallback =
       void ([instanceOf=DOMFileSystem] object fileSystem);
 
-  // [nodoc] A callback type for getUsageAndQuota.
+  // A callback type for getUsageAndQuota.
   callback QuotaAndUsageCallback = void (StorageInfo info);
 
   // Returns true if operation was successful.
   callback DeleteFileSystemCallback = void (boolean result);
 
-  // [nodoc] A callback type for getFileStatus.
+  // A callback type for getFileStatus.
   callback GetFileStatusCallback = void (FileStatus status);
 
   interface Functions {
     // Returns a syncable filesystem backed by Google Drive. 
-    // The returned DOMFileSystem instance can be operated on in the same way as
-    // the Temporary and Persistant file systems.
-    // (http://www.w3.org/TR/file-system-api/). Calling this multiple times from
+    // The returned <code>DOMFileSystem</code> instance can be operated on
+    // in the same way as the Temporary and Persistant file systems (see
+    // <a href="http://www.w3.org/TR/file-system-api/">http://www.w3.org/TR/file-system-api/</a>).
+    // Calling this multiple times from
     // the same app will return the same handle to the same file system. 
     static void requestFileSystem(GetFileSystemCallback callback);
 
-    // Get usage and quota in bytes for sync file system with |serviceName|.
+    // Returns the current usage and quota in bytes
+    // for the <code>'syncable'</code> file storage for the app.
     static void getUsageAndQuota([instanceOf=DOMFileSystem] object fileSystem,
                                  QuotaAndUsageCallback callback);
 
@@ -102,15 +115,17 @@ namespace syncFileSystem {
     static void deleteFileSystem([instanceOf=DOMFileSystem] object fileSystem,
                                  DeleteFileSystemCallback callback);
 
-    // Get the FileStatus for the given |fileEntry|.
+    // Returns the $ref:FileStatus for the given <code>fileEntry</code>.
+    // The status value can be <code>'synced'</code>,
+    // <code>'pending'</code> or <code>'conflicting'</code>.
     static void getFileStatus([instanceOf=FileEntry] object fileEntry,
                               GetFileStatusCallback callback);
   };
 
   interface Events {
     // Fired when an error or other status change has happened in the
-    // sync backend. (e.g. the sync is temporarily disabled due to
-    // network or authentication error etc).
+    // sync backend (for example, when the sync is temporarily disabled due to
+    // network or authentication error).
     static void onServiceStatusChanged(ServiceInfo detail);
 
     // Fired when a file has been updated by the background sync service.
diff --git a/chrome/common/extensions/docs/templates/articles/app_storage.html b/chrome/common/extensions/docs/templates/articles/app_storage.html
index 2d01315..94c898c 100644
--- a/chrome/common/extensions/docs/templates/articles/app_storage.html
+++ b/chrome/common/extensions/docs/templates/articles/app_storage.html
@@ -1,6 +1,5 @@
 <h1>Manage Data</h1>
 
-
 <p>
 Almost every aspect of app development involves some element
 of sending or receiving data.
@@ -16,15 +15,17 @@ You also need to think about how data is handled when your app is offline
 This doc briefly introduces the storage options
 for sending, receiving, and saving data locally;
 the remainder of the doc shows you how
-to use Chrome's File System API
-(see also the <a href="fileSystem.html">fileSystem API</a>).
+to use Chrome's File System and Sync File System APIs
+(see also <a href="fileSystem.html">fileSystem API</a> and
+<a href="syncFileSystem.html">syncFileSystem API</a>).
 </p>
 
 <p class="note">
 <b>API Samples: </b>
 Want to play with the code?
 Check out the
-<a href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/filesystem-access">filesystem-access</a>
+<a href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/filesystem-access">filesystem-access</a>,
+<a href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/syncfs-editor">syncfs-editor</a>
 and <a href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/storage">storage</a> samples.
 </p>
 
@@ -56,24 +57,35 @@ to an object store and use the store's indexes to query data
 <a href="http://www.html5rocks.com/tutorials/indexeddb/todo/">Simple Todo List Tutorial</a>).
 For all other types of data,
 like binary data,
-use the Filesystem API.
+use the Filesystem and Sync Filesystem APIs.
 </p>
 
 <p>
-Chrome's Filesystem API extends the
-<a href="http://www.html5rocks.com/tutorials/file/filesystem/">HTML5 FileSystem API</a>;
+Chrome's Filesystem and Sync Filesystem APIs extend the
+<a href="http://www.html5rocks.com/tutorials/file/filesystem/">HTML5 FileSystem API</a>.
+With Chrome's Filesystem API,
 apps can create, read, navigate,
 and write to a sandboxed section
 of the user's local file system.
-With Chrome's File System API,
-packaged apps can read and write files
-to user-selected locations.
 For example,
-a photo-sharing app can use the File System API
+a photo-sharing app can use the Filesystem API
 to read and write any photos that a user selects.
 </p>
 
-<h2 id="manifest">Adding file system permission</h2>
+<p>
+With Chrome's Sync Filesystem API,
+apps can save and synchronize data
+on a user's Google Drive
+so that the same data can be available across different clients.
+For example, a 
+<a href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/syncfs-editor">cloud-backed text editor</a>
+app can automatically sync new text files to a user's Google Drive account.
+When the user opens the text editor in a new client,
+Google Drive pushes new text files to that instance of the text editor.
+</p>
+
+<h2 id="filesystem">Using the Chrome Filesystem API</h2>
+<h3 id="filesystem-manifest">Adding file system permission</h3>
 
 <p>
 To use Chrome's File System API,
@@ -88,7 +100,7 @@ to store persistent data.
 ]
 </pre>
 
-<h2 id="import">User-options for selecting files</h2>
+<h3 id="import">User-options for selecting files</h3>
 
 <p>
 Users expect to select files
@@ -102,7 +114,7 @@ you should also implement drag-and-drop
 <a href="http://www.html5rocks.com/tutorials/dnd/basics/">Native HTML5 Drag and Drop</a>).
 </p>
 
-<h2 id="path">Obtaining the path of a fileEntry</h2>
+<h3 id="path">Obtaining the path of a fileEntry</h3>
 
 <p>
 To get the full path
@@ -119,13 +131,13 @@ function displayPath(fileEntry) {
 }
 </pre>
 
-<h2 id="drag">Implementing drag-and-drop</h2>
+<h3 id="drag">Implementing drag-and-drop</h3>
 
 <p>
 If you need to implement drag-and-drop selection,
 the drag-and-drop file controller
-(<code>dnd.js</code>) in
-the <a href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/filesystem-access">filesystem-access</a>
+(<code>dnd.js</code>) in the
+<a href="https://github.com/GoogleChrome/chrome-app-samples/tree/master/filesystem-access">filesystem-access</a>
 sample is a good starting point.
 The controller creates a file entry
 from a <code>DataTransferItem</code>
@@ -142,7 +154,7 @@ var dnd = new DnDFileController('body', function(data) {
 });
 </pre>
 
-<h2 id="read">Reading a file</h2>
+<h3 id="read">Reading a file</h3>
 
 <p>
 The following code opens the file (read-only) and
@@ -170,7 +182,7 @@ chooseFileButton.addEventListener('click', function(e) {
 });
 </pre>
 
-<h2 id="write">Writing a file</h2>
+<h3 id="write">Writing a file</h3>
 
 <p>
 The two common use-cases
@@ -213,4 +225,186 @@ chrome.fileSystem.chooseEntry({type: 'saveFile'}, function(writableFileEntry) {
 });
 </pre>
 
+<h2 id="sync-filesystem">Using the Chrome Sync Filesystem API</h2>
+
+<p>
+Using syncable file storage,
+returned data objects can be operated on in the same way
+as local offline file systems in the
+<a href="http://www.w3.org/TR/file-system-api/">FileSystem API</a>,
+but with the added (and automatic) syncing
+of that data to Google Drive.
+</p>
+
+
+<h3 id="sync-manifest">Adding sync file system permission</h3>
+
+<p>
+To use Chrome's Sync Filesystem API,
+you need to add the "syncFileSystem" permission to the manifest,
+so that you can obtain permission from the user
+to store and sync persistent data.
+
+<pre>
+"permissions": [
+  "...",
+  "syncFileSystem"
+]
+</pre>
+
+<h3 id="initiate">Initiating syncable file storage</h3>
+
+<p>
+To initiate syncable file storage in your app,
+simply call $ref:[syncFileSystem.requestFileSystem].
+This method returns a syncable filesystem backed by Google Drive,
+for example:
+</p>
+
+<pre>
+chrome.syncFileSystem.requestFileSystem(function (fs) {
+   // FileSystem API should just work on the returned 'fs'.
+   fs.root.getFile('test.txt', {create:true}, getEntryCallback, errorCallback);
+});
+</pre>
+
+<h3 id="file-status">About file sync status</h3>
+
+<p>
+Use $ref:[syncFileSystem.getFileStatus] to get the sync status
+for a current file:
+</p>
+
+<pre>
+chrome.syncFileSystem.getFileStatus(entry, function(status) {...});
+</pre>
+
+<p>
+File sync status values can be one of the following:
+<code>'synced'</code>, <code>'pending'</code>, or <code>'conflicting'</code>.
+'Synced' means the file is fully synchronized;
+there're no pending local changes
+that haven't been synchronized to Google Drive.
+There can, however, be pending changes on the Google Drive side
+that haven't been fetched yet.
+</p>
+
+<p>
+'Pending' means the file has pending changes
+not yet synchronized to Google Drive.
+If the app is running online,
+local changes are (almost) immediately synchronized to Google Drive, and the
+$ref:[syncFileSystem.onFileStatusChanged]
+event is fired with the <code>'synced'</code> status
+(see below for more details).
+</p>
+
+<p>
+The $ref:[syncFileSystem.onFileStatusChanged]
+is fired when a file's status changes to <code>'conflicting'</code>.
+'Conflicting' means there are conflicting changes
+on both the local storage and Google Drive.
+Currently the API does NOT provide automatic reconciliation mechanism
+for conflicting files.
+</p>
+
+<p>
+If no action is taken,
+the app can continue to read/write the file as a detached local offline file,
+but the file will be kept detached from the remote changes made on other clients.
+The conflict is automatically resolved
+once the local or conflicting version is deleted.
+For example,
+when a file is in conflicting state,
+the app can delete or rename the local version.
+This forces the remote version to be synchronized,
+the conflicting state is resolved, and
+the <code>onFileStatusChanged</code> event is fired
+with the <code>'synced'</code> status.
+</p>
+
+<h3 id="file-status">Listening for changes in synced status</h3>
+
+<p>
+The
+$ref:[syncFileSystem.onFileStatusChanged]
+event is fired when the sync status of a file changes.
+For example,
+assume a file has pending changes and is in the 'pending' state.
+The app may have been in offline state so that
+the change is about to be synchronized.
+When the sync service detects the pending local change
+and uploads the change to Google Drive,
+the service fires the <code>onFileStatusChanged</code> event
+with following values:
+<code>{ fileEntry:a fileEntry for the file, status: 'synced', action: 'updated',
+  direction: 'local_to_remote' }</code>.
+</p>
+
+<p>
+Similarly, regardless of the local activities,
+the sync service may detect remote changes made by another client,
+and downloads the changes from Google Drive to the local storage.
+If the remote change was for adding a new file,
+an event with following values is fired:
+<code>{ fileEntry: a fileEntry for the file, status: 'synced', action: 'added',
+  direction: 'remote_to_local' }</code>.
+</p>
+
+<p>
+If both the local and remote side have conflicting changes for the same file,
+the file status is changed to <code>conflicting</code> state,
+is detached from the sync service,
+and won't be synchronized until the conflict is resolved.
+In this case an event with following values is fired:
+<code>{ fileEntry: a fileEntry for the file, status: 'conflicting', action: null,
+  direction: null }</code>.
+</p>
+
+<p>
+You can add a listener for this event
+that responds to any changes in status.
+For example,
+the <a href="https://github.com/agektmr/ChromeMusicPlayer">Chrome Music Player</a> app
+listens for any new music synced from Google Drive,
+but not yet imported to the user's local storage on a particular client.
+Any music found gets synced to that client:
+</p>
+
+<pre>
+chrome.syncFileSystem.onFileStatusChanged.addListener(function(fileInfo) {
+  if (fileInfo.status === 'synced') {
+    if (fileInfo.direction === 'remote_to_local') { 
+      if (fileInfo.action === 'added') {
+        db.add(fileInfo.fileEntry);
+      } else if (fileInfo.action === 'deleted') {
+        db.remove(fileInfo.fileEntry);
+      }
+    }
+  }
+});
+</pre>
+
+<h3 id="check-usage">Checking API usage</h3>
+
+<p>
+To check the amount of data being used by the API,
+query the app's local sandboxed directory
+or the usage bytes returned by
+$ref:[syncFileSystem.getUsageAndQuota]:
+</p>
+
+<pre>
+chrome.syncFileSystem.getUsageAndQuota(fileSystem, function (storageInfo) {
+   updateUsageInfo(storageInfo.usageBytes);
+   updateQuotaInfo(storageInfo.quotaBytes);
+});
+</pre>
+
+<p>
+You can also look at the user's sync backend service storage (in Google Drive).
+Synced files are saved in the Google Drive folder,
+<strong>Chrome Syncable FileSystem</strong>.
+</p>
+
 <p class="backtotop"><a href="#top">Back to top</a></p>
\ No newline at end of file
diff --git a/chrome/common/extensions/docs/templates/articles/declare_permissions.html b/chrome/common/extensions/docs/templates/articles/declare_permissions.html
index 33df369..a556b83 100644
--- a/chrome/common/extensions/docs/templates/articles/declare_permissions.html
+++ b/chrome/common/extensions/docs/templates/articles/declare_permissions.html
@@ -261,6 +261,14 @@ table.
   <td> Required if the extension or app uses the
        <a href="storage.html">chrome.storage</a> module. </td>
 </tr>
+{{?is_apps}}
+<tr>
+  <td id="syncFileSystem"> "syncFileSystem" </td>
+  <td> Required if the app uses the
+       <a href="syncFileSystem.html">syncFileSystem API</a>
+       to save and synchronize data on Google Drive.</td>
+</tr>
+{{/is_apps}}
 {{^is_apps}}
 <tr>
   <td> "tabs" </td>
diff --git a/chrome/common/extensions/docs/templates/intros/syncFileSystem.html b/chrome/common/extensions/docs/templates/intros/syncFileSystem.html
new file mode 100644
index 0000000..5471dc8
--- /dev/null
+++ b/chrome/common/extensions/docs/templates/intros/syncFileSystem.html
@@ -0,0 +1,32 @@
+<table class="intro">
+  <tr>
+    <th scope="col"></th>
+    <th scope="col"></th>
+  </tr>
+  <tr>
+    <td><strong>Description:</strong></td>
+    <td>Use the <code>chrome.syncFileSystem</code> API
+    to save and synchronize data on Google Drive.
+    This API is NOT for accessing arbitrary user docs stored in Google Drive.
+    It provides app-specific syncable storage for offline and caching usage
+    so that the same data can be available across different clients.
+    Read <a href="http://developer.chrome.com/trunk/apps/app_storage.html">Manage Data</a>
+    for more on using this API.</td>
+  </tr>
+  <tr>
+    <td><strong>Availability:</strong></td>
+    <td>Google Chrome Dev Channel Only</td>
+  </tr>
+  <tr>
+    <td><strong>Permissions:</strong></td>
+    <td><code>"syncFileSystem"</code></td>
+  </tr>
+  <tr>
+    <td><strong>Learn more:</strong></td>
+    <td><a href="http://developer.chrome.com/trunk/apps/app_storage.html">Manage Data</a>;<br>
+    <a href="https://developers.google.com/live/shows/83992232-2001/">Chrome Office Hours: Synched File System</a>
+    </td>
+  </tr>
+</table>
+
+
diff --git a/chrome/common/extensions/docs/templates/public/apps/syncFileSystem.html b/chrome/common/extensions/docs/templates/public/apps/syncFileSystem.html
new file mode 100644
index 0000000..ece3a8e
--- /dev/null
+++ b/chrome/common/extensions/docs/templates/public/apps/syncFileSystem.html
@@ -0,0 +1 @@
+{{+partials.standard_apps_api api:apis.sync_file_system intro:intros.syncFileSystem}}