[fsp] Cleanup IDL.

chrome/common/extensions/api/file_system_provider.idl

 // Copyright 2013 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 // Use the <code>chrome.fileSystemProvider</code> API to create file systems,
 // that can be accessible from the file manager on Chrome OS.
 [platforms=("chromeos"),
  implemented_in="chrome/browser/chromeos/extensions/file_system_provider/file_system_provider_api.h"]
 namespace fileSystemProvider {
   // Error codes used by providing extensions in response to requests. For
-  // success, <code>OK</code> should be used.
+  // success, <code>OK</code> must be used.
   enum ProviderError {
     OK,
     FAILED,
     IN_USE,
     EXISTS,
     NOT_FOUND,
     ACCESS_DENIED,
     TOO_MANY_OPENED,
     NO_MEMORY,
     NO_SPACE,
@@ skipping 13 matching lines @@
   };
 
   // Represents metadata of a file or a directory.
   dictionary EntryMetadata {
     // True if it is a directory.
     boolean isDirectory;
 
     // Name of this entry (not full path name).
     DOMString name;
 
     // File size in bytes.

[mtomasz, 2014/09/03 04:01:18]

Should it be "The file size in bytes"?

     double size;
 
     // The last modified time of this entry.
     [instanceOf=Date] object modificationTime;
 
     // Mime type for the entry.
     DOMString? mimeType; 
   };
 
   // Represents a mounted file system.
   dictionary FileSystemInfo {
-    DOMString fileSystemId;
+    // An identifier of the file system.

[benwells, 2014/09/03 01:19:38]

s/An/The/

[mtomasz, 2014/09/03 04:01:18]

Done.

+    DOMString fileSystemId;
+
+    // A human-readable name of the file system. 

[benwells, 2014/09/03 01:19:38]

s/of/for/

[mtomasz, 2014/09/03 04:01:18]

Should it be "The human-readable name..."?

[mtomasz, 2014/09/03 04:01:19]

Done.

     DOMString displayName;
+
+    // Whether the file system supports contents changing operations.

[benwells, 2014/09/03 01:19:37]

This isn't a very typical way of describing this. How about what you have below
(line 76)?

[mtomasz, 2014/09/03 04:01:18]

Done.

     [nodoc] boolean writable;
   };
 
   // Options for the <code>mount()</code> method.
   dictionary MountOptions {
-    DOMString fileSystemId;
+    // A string indentifier of the file system. Must be unique per each

[benwells, 2014/09/03 01:19:38]

s/A/The/

[mtomasz, 2014/09/03 04:01:18]

Done.

+    // extension.
+    DOMString fileSystemId;
+
+    // A human-readable name of the file system. 

[benwells, 2014/09/03 01:19:38]

s/of/for/

[mtomasz, 2014/09/03 04:01:18]

Done.

     DOMString displayName;
+
+    // Whether the file system supports operations which may change contents
+    // of the file system (such as creating, deleting or writing to files).
     [nodoc] boolean? writable;
   };
 
   // Options for the <code>unmount()</code> method.
   dictionary UnmountOptions {
+    // An identifier of the file system to be unmounted.

[benwells, 2014/09/03 01:19:38]

s/An/The/

[mtomasz, 2014/09/03 04:01:18]

Done.

     DOMString fileSystemId;
   };
 
   // Options for the <code>onUnmountRequested()</code> event.
   dictionary UnmountRequestedOptions {
+    // An identifier of the file system to be unmounted.

[benwells, 2014/09/03 01:19:38]

s/An/The/

[mtomasz, 2014/09/03 04:01:18]

Done.

     DOMString fileSystemId;
     long requestId;
   };
 
   // Options for the <code>onGetMetadataRequested()</code> event.
   dictionary GetMetadataRequestedOptions {
-    DOMString fileSystemId;
-    long requestId;
+    // An identifier of the file system related to this operation.

[benwells, 2014/09/03 01:19:38]

s/An/The/

(same for all options dictionaries).

[mtomasz, 2014/09/03 04:01:19]

Done.

+    DOMString fileSystemId;
+
+    // Unique identifier of this request.

[benwells, 2014/09/03 01:19:38]

The unique...

(same for all options dictionaries).

+    long requestId;
+
+    // A path of the entry to fetch metadata about.

[benwells, 2014/09/03 01:19:38]

s/A/The/

(same for all options dictionaries).

     DOMString entryPath;
   };
 
   // Options for the <code>onReadDirectoryRequested()</code> event.
   dictionary ReadDirectoryRequestedOptions {
-    DOMString fileSystemId;
-    long requestId;
+    // An identifier of the file system related to this operation.
+    DOMString fileSystemId;
+
+    // Unique identifier of this request.
+    long requestId;
+
+    // A path of the directory which contents are requested. 
     DOMString directoryPath;
   };
 
   // Options for the <code>onOpenFileRequested()</code> event.
   dictionary OpenFileRequestedOptions {
-    DOMString fileSystemId;
-    long requestId;
+    // An identifier of the file system related to this operation.
+    DOMString fileSystemId;
+
+    // A request ID which will be used by consecutive read/write and close

[mtomasz, 2014/09/03 04:01:18]

Shall it be "The request ID"? WDYT?

[benwells, 2014/09/03 05:22:16]

I think this one is OK as is.

+    // requests.
+    long requestId;
+
+    // A path of the file to be opened.
     DOMString filePath;
+
+    // Whether the file will be used for reading or writing.
     OpenFileMode mode;
   };
 
   // Options for the <code>onCloseFileRequested()</code> event.
   dictionary CloseFileRequestedOptions {
-    DOMString fileSystemId;
-    long requestId;
+    // An identifier of the file system related to this operation.
+    DOMString fileSystemId;
+
+    // Unique identifier of this request.
+    long requestId;
+
+    // A request ID used to open the file.
     long openRequestId;
   };
 
   // Options for the <code>onReadFileRequested()</code> event.
   dictionary ReadFileRequestedOptions {
-    DOMString fileSystemId;
-    long requestId;
+    // An identifier of the file system related to this operation.
+    DOMString fileSystemId;
+
+    // Unique identifier of this request.
+    long requestId;
+
+    // A request ID used to open the file.
     long openRequestId;
+
+    // Position in the file (in bytes) to start reading from.
     double offset;
+
+    // Number of bytes to be returned.
     double length;
   };
 
   // Options for the <code>onCreateDirectoryRequested()</code> event.
   dictionary CreateDirectoryRequestedOptions {
-    DOMString fileSystemId;
-    long requestId;
+    // An identifier of the file system related to this operation.
+    DOMString fileSystemId;
+
+    // Unique identifier of this request.
+    long requestId;
+
+    // A path of the directory to be created.
     DOMString directoryPath;
+
+    // Whether the the operation must fail if the directory already exists.
     boolean exclusive;
+
+    // Whether the operation is recursive (for directories only).

[benwells, 2014/09/03 01:19:38]

I'm unclear what this means for create directory. Does it mean to create all
necessary parents?

[mtomasz, 2014/09/03 04:01:18]

Yes. More information is in the comment for onCreateDirectoryRequested. I wanted
to avoid duplication. WDYT?

[benwells, 2014/09/03 05:22:16]

OK, no problem.

     boolean recursive;
   };
 
   // Options for the <code>onDeleteEntryRequested()</code> event.
   dictionary DeleteEntryRequestedOptions {
-    DOMString fileSystemId;
-    long requestId;
+    // An identifier of the file system related to this operation.
+    DOMString fileSystemId;
+
+    // Unique identifier of this request.
+    long requestId;
+
+    // A path of the entry to be deleted.
     DOMString entryPath;
+
+    // Whether the operation is recursive (for directories only).
     boolean recursive;
   };
 
   // Options for the <code>onCreateFileRequested()</code> event.
   dictionary CreateFileRequestedOptions {
-    DOMString fileSystemId;
-    long requestId;
+    // An identifier of the file system related to this operation.
+    DOMString fileSystemId;
+
+    // Unique identifier of this request.
+    long requestId;
+
+    // A path of the file to be created.
     DOMString filePath;
   };
 
   // Options for the <code>onCopyEntryRequested()</code> event.
   dictionary CopyEntryRequestedOptions {
-    DOMString fileSystemId;
-    long requestId;
+    // An identifier of the file system related to this operation.
+    DOMString fileSystemId;
+
+    // Unique identifier of this request.
+    long requestId;
+
+    // A source path of the entry to be copied.
     DOMString sourcePath;
+
+    // A destination path for the copy operation.
     DOMString targetPath;
   };
 
   // Options for the <code>onMoveEntryRequested()</code> event.
   dictionary MoveEntryRequestedOptions {
-    DOMString fileSystemId;
-    long requestId;
+    // An identifier of the file system related to this operation.
+    DOMString fileSystemId;
+
+    // Unique identifier of this request.
+    long requestId;
+
+    // A source path of the entry to be moved into a new place.
     DOMString sourcePath;
+
+    // A destination path for the copy operation.
     DOMString targetPath;
   };
 
   // Options for the <code>onTruncateRequested()</code> event.
   dictionary TruncateRequestedOptions {
-    DOMString fileSystemId;
-    long requestId;
+    // An identifier of the file system related to this operation.
+    DOMString fileSystemId;
+
+    // Unique identifier of this request.
+    long requestId;
+
+    // A path of the file to be truncated.
     DOMString filePath;
+
+    // Number of bytes to be retained after the operation completes.
     double length;
   };
 
   // Options for the <code>onWriteFileRequested()</code> event.
   dictionary WriteFileRequestedOptions {
-    DOMString fileSystemId;
-    long requestId;
+    // An identifier of the file system related to this operation.
+    DOMString fileSystemId;
+
+    // Unique identifier of this request.
+    long requestId;
+
+    // A request ID used to open the file.
     long openRequestId;
+
+    // Position in the file (in bytes) to start writing the bytes at.

[benwells, 2014/09/03 01:19:38]

s/at/from/

     double offset;
-    double length;
+
+    // Buffer of bytes to be written to the file.
     ArrayBuffer data;
   };
 
   // Options for the <code>onAbortRequested()</code> event.
   dictionary AbortRequestedOptions {
-    DOMString fileSystemId;
-    long requestId;
+    // An identifier of the file system related to this operation.
+    DOMString fileSystemId;
+
+    // Unique identifier of this request.
+    long requestId;
+
+    // An ID of the request to be aborted.
     long operationRequestId;
   };
 
   // Callback to receive the result of mount() function.
   callback MountCallback = void([nodoc, instanceOf=DOMError] object error);
 
   // Callback to receive the result of unmount() function.
   callback UnmountCallback = void([nodoc, instanceOf=DOMError] object error);
 
   // Callback to receive the result of getAll() function.
@@ skipping 21 matching lines @@
   // data will be returned, then <code>hasMore</code> must be true, and it
   // has to be called again with additional entries. If no more data is
   // available, then <code>hasMore</code> must be set to false.
   callback FileDataCallback = void(ArrayBuffer data, boolean hasMore);
 
   interface Functions {
     // Mounts a file system with the given <code>fileSystemId</code> and <code>
     // displayName</code>. <code>displayName</code> will be shown in the left
     // panel of Files.app. <code>displayName</code> can contain any characters
     // including '/', but cannot be an empty string. <code>displayName</code>
-    // should be descriptive but doesn't have to be unique. Duplicate display
+    // must be descriptive but doesn't have to be unique. Duplicate display
     // names are uniquified by adding suffix like "(1)" in the Files app UI.
     //
     // If a file system with the passed <code>fileSystemId</code> is already
     // mounted by this extension, then <code>errorCallback</code> will be called
     // with <code>ProviderError.EXISTS</code> value. The <code>fileSystemId
     // </code> must not be an empty string.
     static void mount(MountOptions options,
                       MountCallback successCallback,
                       [nocompile] ErrorCallback errorCallback);
 
     // Unmounts a file system with the given <code>fileSystemId</code>. It
-    // should be called after <code>onUnmountRequested</code> is invoked. Also,
+    // must be called after <code>onUnmountRequested</code> is invoked. Also,
     // the providing extension can decide to perform unmounting if not requested
     // (eg. in case of lost connection, or a file error). If there is no file
     // system with the requested id, or unmounting fails, then the
     // <code>errorCallback</code> will be called.
     static void unmount(UnmountOptions options,
                         UnmountCallback successCallback,
                         [nocompile] ErrorCallback errorCallback);
 
     // Returns all file systems mounted by the extension.
     static void getAll(GetAllCallback callback);
   };
 
   interface Events {
     // Raised when unmounting for the file system with the <code>fileSystemId
     // </code> identifier is requested. In the response, the <code>unmount
-    // </code> API method should be called together with <code>successCallback
+    // </code> API method must be called together with <code>successCallback
     // </code>. If unmounting is not possible (eg. due to a pending operation),
     // then <code>errorCallback</code> must be called.
     [maxListeners=1] static void onUnmountRequested(
         UnmountRequestedOptions options,
         ProviderSuccessCallback successCallback,
         ProviderErrorCallback errorCallback);
 
     // Raised when metadata of a file or a directory at <code>entryPath</code>
-    // is requested. The metadata should be returned with the <code>
+    // is requested. The metadata must be returned with the <code>
     // successCallback</code> call. In case of an error, <code>errorCallback
     // </code> must be called.
     [maxListeners=1] static void onGetMetadataRequested(
         GetMetadataRequestedOptions options,
         MetadataCallback successCallback,
         ProviderErrorCallback errorCallback);
 
     // Raised when contents of a directory at <code>directoryPath</code> are
-    // requested. The results should be returned in chunks by calling the <code>
+    // requested. The results must be returned in chunks by calling the <code>
     // successCallback</code> several times. In case of an error, <code>
     // errorCallback</code> must be called.
     [maxListeners=1] static void onReadDirectoryRequested(
         ReadDirectoryRequestedOptions options,
         EntriesCallback successCallback,
         ProviderErrorCallback errorCallback);
 
     // Raised when opening a file at <code>filePath</code> is requested. If the
     // file does not exist, then the operation must fail.
     [maxListeners=1] static void onOpenFileRequested(
         OpenFileRequestedOptions options,
         ProviderSuccessCallback successCallback,
         ProviderErrorCallback errorCallback);
 
     // Raised when opening a file previously opened with <code>openRequestId
     // </code> is requested to be closed.
     [maxListeners=1] static void onCloseFileRequested(
         CloseFileRequestedOptions options,
         ProviderSuccessCallback successCallback,
         ProviderErrorCallback errorCallback);
 
     // Raised when reading contents of a file opened previously with <code>
-    // openRequestId</code> is requested. The results should be returned in
+    // openRequestId</code> is requested. The results must be returned in
     // chunks by calling <code>successCallback</code> several times. In case of
     // an error, <code>errorCallback</code> must be called.
     [maxListeners=1] static void onReadFileRequested(
         ReadFileRequestedOptions options,
         FileDataCallback successCallback,
         ProviderErrorCallback errorCallback);
 
     // Raised when creating a directory is requested. If <code>exclusive</code>
     // is set to true, then the operation must fail if the target directory
     // already exists. If <code>recursive</code> is true, then all of the
@@ skipping 42 matching lines @@
 
     // Raised when writing contents to a file opened previously with <code>
     // openRequestId</code> is requested.
     [maxListeners=1, nodoc] static void onWriteFileRequested(
         WriteFileRequestedOptions options,
         ProviderSuccessCallback successCallback,
         ProviderErrorCallback errorCallback);
 
     // Raised when aborting an operation with <code>operationRequestId</code>
     // is requested. The operation executed with <code>operationRequestId</code>
-    // should be immediately stopped and <code>successCallback</code> of this
+    // must be immediately stopped and <code>successCallback</code> of this
     // abort request executed. If aborting fails, then <code>errorCallback
     // </code> must be called. Note, that callbacks of the aborted operation
-    // should not be called, as they will be ignored. Despite calling <code>
+    // must not be called, as they will be ignored. Despite calling <code>
     // errorCallback</code>, the request may be forcibly aborted. 
     [maxListeners=1, nodoc] static void onAbortRequested(
         AbortRequestedOptions options,
         ProviderSuccessCallback successCallback,
         ProviderErrorCallback errorCallback);
   };
 };