:memo: Revise the dialog API docs.

diff --git a/docs/api/browser/dialog.md b/docs/api/browser/dialog.md
index 0ded6b49735caf5db96c004eced2f9f8444dcbb7..d6ae8f3363eaa339cfdcd376a96c3325a8997597 100644 (file)
--- a/docs/api/browser/dialog.md
+++ b/docs/api/browser/dialog.md
@@ -1,6 +1,6 @@
 # dialog
 
-The `dialog` module provides functions to show system dialogs, so web
+The `dialog` module provides APIs to show native system dialogs, so web
 applications can get the same user experience with native applications.
 
 An example of showing a dialog to select multiple files and directories:
@@ -11,33 +11,43 @@ var dialog = require('dialog');
 console.log(dialog.showOpenDialog({ properties: [ 'openFile', 'openDirectory', 'multiSelections' ]}));
 ```
 
-## dialog.showOpenDialog(options)
+## dialog.showOpenDialog([browserWindow], options, [callback])
 
+* `browserWindow` BrowserWindow
 * `options` Object
   * `title` String
-  * `defaultPath` String  
+  * `defaultPath` String
   * `properties` Array - Contains which features the dialog should use, can
     contain `openFile`, `openDirectory`, `multiSelections` and
     `createDirectory`
+* `callback` Function
 
 On success, returns an array of file paths chosen by the user, otherwise
 returns `undefined`.
 
-**Note:** The `dialog.showOpenDialog` API is synchronous and blocks all windows.
+If a `callback` is passed, the API call would be asynchronous and the result
+would be passed via `callback(filenames)`
+
+**Note:** On Windows and Linux, an open dialog could not be both file selector
+and directory selector at the same time, so if you set `properties` to
+`['openFile', 'openDirectory']` on these platforms, a directory selector would
+be showed.
 
-## dialog.showSaveDialog(browserWindow, options)
+## dialog.showSaveDialog([browserWindow], options, [callback])
 
 * `browserWindow` BrowserWindow
 * `options` Object
   * `title` String
   * `defaultPath` String
+* `callback` Function
 
 On success, returns the path of file chosen by the user, otherwise returns
 `undefined`.
 
-**Note:** The `dialog.showSaveDialog` API is synchronous and blocks all windows.
+If a `callback` is passed, the API call would be asynchronous and the result
+would be passed via `callback(filename)`
 
-## dialog.showMessageBox([browserWindow], options)
+## dialog.showMessageBox([browserWindow], options, [callback])
 
 * `browserWindow` BrowserWindow
 * `options` Object
@@ -46,8 +56,10 @@ On success, returns the path of file chosen by the user, otherwise returns
   * `title` String - Title of the message box, some platforms will not show it
   * `message` String - Content of the message box
   * `detail` String - Extra information of the message
+* `callback` Function
 
 Shows a message box, it will block until the message box is closed. It returns
 the index of the clicked button.
 
-**Note:** The `dialog.showMessageBox` API is synchronous and blocks all windows.
+If a `callback` is passed, the API call would be asynchronous and the result
+would be passed via `callback(response)`