More docs updates

docs/api/browser-window.md

@@ -157,7 +157,7 @@ It creates a new `BrowserWindow` with native properties as set by the `options`.
     `false`.
   * `kiosk` Boolean (optional) - The kiosk mode. Default is `false`.
   * `title` String (optional) - Default window title. Default is `"Electron"`.
-  * `icon` [NativeImage](native-image.md) (optional) - The window icon. On Windows it is
+  * `icon` ([NativeImage](native-image.md) | String) (optional) - The window icon. On Windows it is
     recommended to use `ICO` icons to get best visual effects, you can also
     leave it undefined so the executable's icon will be used.
   * `show` Boolean (optional) - Whether window should be shown when created. Default is
@@ -948,7 +948,7 @@ bar will become gray when set to `true`.
 
 #### `win.isDocumentEdited()` _macOS_
 
-Whether `Boolean` - Whether the window's document has been edited.
+Returns `Boolean` - Whether the window's document has been edited.
 
 #### `win.focusOnWebView()`
 
@@ -964,7 +964,7 @@ Same as `webContents.capturePage([rect, ]callback)`.
 
 #### `win.loadURL(url[, options])`
 
-* `url` URL
+* `url` String
 * `options` Object (optional)
   * `httpReferrer` String (optional) - A HTTP Referrer url.
   * `userAgent` String (optional) - A user agent originating the request.

docs/api/dialog.md

@@ -27,19 +27,19 @@ The `dialog` module has the following methods:
 
 * `browserWindow` BrowserWindow (optional)
 * `options` Object
-  * `title` String
+  * `title` String (optional)
   * `defaultPath` String (optional)
   * `buttonLabel` String (optional) - Custom label for the confirmation button, when
     left empty the default label will be used.
-  * `filters` String[] (optional)
+  * `filters` [FileFilter[]](structrs/file-filter.md) (optional)
   * `properties` String[] (optional) - Contains which features the dialog should use, can
     contain `openFile`, `openDirectory`, `multiSelections`, `createDirectory`
     and `showHiddenFiles`.
 * `callback` Function (optional)
   * `filePaths` String[] - An array of file paths chosen by the user
 
-On success this method returns an array of file paths chosen by the user,
+Returns `String[]`, an array of file paths chosen by the user,
-otherwise it returns `undefined`.
+if the callback is provided it returns `undefined`.
 
 The `filters` specifies an array of file types that can be displayed or
 selected when you want to limit the user to a specific type. For example:
@@ -71,16 +71,16 @@ shown.
 
 * `browserWindow` BrowserWindow (optional)
 * `options` Object
-  * `title` String
+  * `title` String (optional)
   * `defaultPath` String (optional)
   * `buttonLabel` String (optional) - Custom label for the confirmation button, when
     left empty the default label will be used.
-  * `filters` String[] (optional)
+  * `filters` [FileFilter[]](structrs/file-filter.md) (optional)
 * `callback` Function (optional)
   * `filename` String
 
-On success this method returns the path of the file chosen by the user,
+Returns `String`, the path of the file chosen by the user,
-otherwise it returns `undefined`.
+if a callback is provided it returns `undefined`.
 
 The `filters` specifies an array of file types that can be displayed, see
 `dialog.showOpenDialog` for an example.
@@ -113,9 +113,12 @@ will be passed via `callback(filename)`
     others as command links in the dialog. This can make the dialog appear in
     the style of modern Windows apps. If you don't like this behavior, you can
     set `noLink` to `true`.
-* `callback` Function
+* `callback` Function (optional)
   * `response` Number - The index of the button that was clicked
 
+Returns `Integer`, the index of the clicked button, if a callback is provided
+it returns undefined.
+
 Shows a message box, it will block the process until the message box is closed.
 It returns the index of the clicked button.
 

docs/api/ipc-renderer.md

@@ -14,7 +14,7 @@ See [ipcMain](ipc-main.md) for code examples.
 
 ## Methods
 
-The `ipcRenderer` module has the following method to listen for events:
+The `ipcRenderer` module has the following method to listen for events and send messages:
 
 ### `ipcRenderer.on(channel, listener)`
 
@@ -46,14 +46,10 @@ Removes the specified `listener` from the listener array for the specified
 
 Removes all listeners, or those of the specified `channel`.
 
-## Sending Messages
-
-The `ipcRenderer` module has the following methods for sending messages:
-
 ### `ipcRenderer.send(channel[, arg1][, arg2][, ...])`
 
 * `channel` String
-* `arg` (optional)
+* `...args` any[]
 
 Send a message to the main process asynchronously via `channel`, you can also
 send arbitrary arguments. Arguments will be serialized in JSON internally and
@@ -64,7 +60,7 @@ The main process handles it by listening for `channel` with `ipcMain` module.
 ### `ipcRenderer.sendSync(channel[, arg1][, arg2][, ...])`
 
 * `channel` String
-* `arg` (optional)
+* `...args` any[]
 
 Send a message to the main process synchronously via `channel`, you can also
 send arbitrary arguments. Arguments will be serialized in JSON internally and
@@ -79,7 +75,7 @@ unless you know what you are doing you should never use it.
 ### `ipcRenderer.sendToHost(channel[, arg1][, arg2][, ...])`
 
 * `channel` String
-* `arg` (optional)
+* `...args` any[]
 
 Like `ipcRenderer.send` but the event will be sent to the `<webview>` element in
 the host page instead of the main process.

docs/api/menu-item.md

@@ -13,31 +13,31 @@ Create a new `MenuItem` with the following method:
 ### `new MenuItem(options)`
 
 * `options` Object
-  * `click` Function - Will be called with
+  * `click` Function - (optional) Will be called with
     `click(menuItem, browserWindow, event)` when the menu item is clicked.
     * `menuItem` MenuItem
     * `browserWindow` BrowserWindow
     * `event` Event
-  * `role` String - Define the action of the menu item, when specified the
+  * `role` String - (optional) Define the action of the menu item, when specified the
     `click` property will be ignored.
-  * `type` String - Can be `normal`, `separator`, `submenu`, `checkbox` or
+  * `type` String - (optional) Can be `normal`, `separator`, `submenu`, `checkbox` or
     `radio`.
-  * `label` String
+  * `label` String - (optional)
-  * `sublabel` String
+  * `sublabel` String - (optional)
-  * `accelerator` [Accelerator](accelerator.md)
+  * `accelerator` [Accelerator](accelerator.md) - (optional)
-  * `icon` [NativeImage](native-image.md)
+  * `icon` ([NativeImage](native-image.md) | String) - (optional)
-  * `enabled` Boolean - If false, the menu item will be greyed out and
+  * `enabled` Boolean - (optional) If false, the menu item will be greyed out and
     unclickable.
-  * `visible` Boolean - If false, the menu item will be entirely hidden.
+  * `visible` Boolean - (optional) If false, the menu item will be entirely hidden.
-  * `checked` Boolean - Should only be specified for `checkbox` or `radio` type
+  * `checked` Boolean - (optional) Should only be specified for `checkbox` or `radio` type
     menu items.
-  * `submenu` Menu - Should be specified for `submenu` type menu items. If
+  * `submenu` Menu - (optional) Should be specified for `submenu` type menu items. If
     `submenu` is specified, the `type: 'submenu'` can be omitted. If the value
     is not a `Menu` then it will be automatically converted to one using
     `Menu.buildFromTemplate`.
-  * `id` String - Unique within a single menu. If defined then it can be used
+  * `id` String - (optional) Unique within a single menu. If defined then it can be used
     as a reference to this item by the position attribute.
-  * `position` String - This field allows fine-grained definition of the
+  * `position` String - (optional) This field allows fine-grained definition of the
     specific location within a given menu.
 
 It is best to specify `role` for any menu item that matches a standard role,

docs/api/structures/file-filter.md

@@ -0,0 +1,4 @@
+# FileFilter Object
+
+* `name` String
+* `extensions` String[]

docs/api/structures/jump-list-category.md

@@ -10,9 +10,9 @@
     of the category and its items are set by Windows. Items may be added to
     this category indirectly using `app.addRecentDocument(path)`.
   * `custom` - Displays tasks or file links, `name` must be set by the app.
-* `name` String - Must be set if `type` is `custom`, otherwise it should be
+* `name` String - (optional) Must be set if `type` is `custom`, otherwise it should be
   omitted.
-* `items` JumpListItem[] - Array of [`JumpListItem`](jump-list-item.md) objects if `type` is `tasks` or
+* `items` JumpListItem[] - (optional) Array of [`JumpListItem`](jump-list-item.md) objects if `type` is `tasks` or
   `custom`, otherwise it should be omitted.
 
 **Note:** If a `JumpListCategory` object has neither the `type` nor the `name`

docs/api/structures/jump-list-item.md

@@ -7,16 +7,16 @@
   * `file` - A file link will open a file using the app that created the
     Jump List, for this to work the app must be registered as a handler for
     the file type (though it doesn't have to be the default handler).
-* `path` String - Path of the file to open, should only be set if `type` is
+* `path` String - (optional) Path of the file to open, should only be set if `type` is
   `file`.
-* `program` String - Path of the program to execute, usually you should
+* `program` String - (optional) Path of the program to execute, usually you should
   specify `process.execPath` which opens the current program. Should only be
   set if `type` is `task`.
-* `args` String - The command line arguments when `program` is executed. Should
+* `args` String - (optional) The command line arguments when `program` is executed. Should
   only be set if `type` is `task`.
-* `title` String - The text to be displayed for the item in the Jump List.
+* `title` String - (optional) The text to be displayed for the item in the Jump List.
   Should only be set if `type` is `task`.
-* `description` String - Description of the task (displayed in a tooltip).
+* `description` String - (optional) Description of the task (displayed in a tooltip).
   Should only be set if `type` is `task`.
 * `iconPath` String - The absolute path to an icon to be displayed in a
   Jump List, which can be an arbitrary resource file that contains an icon

docs/api/web-contents.md

@@ -952,6 +952,7 @@ Opens the developer tools for the service worker context.
 #### `contents.send(channel[, arg1][, arg2][, ...])`
 
 * `channel` String
+* `...args` any[]
 
 Send an asynchronous message to renderer process via `channel`, you can also
 send arbitrary arguments. Arguments will be serialized in JSON internally and