Merge pull request #8309 from electron/optional-before-dash

Put optional label before dash

docs/api/app.md

@@ -467,7 +467,7 @@ Clears the recent documents list.
   app to handle `electron://` links, call this method with `electron` as the
   parameter.
 * `path` String (optional) _Windows_ - Defaults to `process.execPath`
-* `args` String[] - (optional) _Windows_ - Defaults to an empty array
+* `args` String[] (optional) _Windows_ - Defaults to an empty array
 
 Returns `Boolean` - Whether the call succeeded.
 
@@ -491,7 +491,7 @@ The API uses the Windows Registry and LSSetDefaultHandlerForURLScheme internally
 
 * `protocol` String - The name of your protocol, without `://`.
 * `path` String (optional) _Windows_ - Defaults to `process.execPath`
-* `args` String[] - (optional) _Windows_ - Defaults to an empty array
+* `args` String[] (optional) _Windows_ - Defaults to an empty array
 
 Returns `Boolean` - Whether the call succeeded.
 
@@ -503,7 +503,7 @@ protocol (aka URI scheme). If so, it will remove the app as the default handler.
 
 * `protocol` String - The name of your protocol, without `://`.
 * `path` String (optional) _Windows_ - Defaults to `process.execPath`
-* `args` String[] - (optional) _Windows_ - Defaults to an empty array
+* `args` String[] (optional) _Windows_ - Defaults to an empty array
 
 Returns `Boolean`
 

docs/api/browser-window.md

@@ -202,10 +202,10 @@ It creates a new `BrowserWindow` with native properties as set by the `options`.
   * `thickFrame` Boolean (optional) - Use `WS_THICKFRAME` style for frameless windows on
     Windows, which adds standard window frame. Setting it to `false` will remove
     window shadow and window animations. Default is `true`.
-  * `vibrancy` String - (optional) Add a type of vibrancy effect to the window, only on
+  * `vibrancy` String (optional) - Add a type of vibrancy effect to the window, only on
     macOS. Can be `appearance-based`, `light`, `dark`, `titlebar`, `selection`,
     `menu`, `popover`, `sidebar`, `medium-light` or `ultra-dark`.
-  * `zoomToPageWidth` Boolean - (optional) Controls the behavior on macOS when
+  * `zoomToPageWidth` Boolean (optional) - Controls the behavior on macOS when
     option-clicking the green stoplight button on the toolbar or by clicking the
     Window > Zoom menu item. If `true`, the window will grow to the preferred
     width of the web page when zoomed, `false` will cause it to zoom to the
@@ -1098,7 +1098,7 @@ The `buttons` is an array of `Button` objects:
     toolbar.
   * `click` Function
   * `tooltip` String (optional) - The text of the button's tooltip.
-  * `flags` String[] - (optional) - Control specific states and behaviors of the
+  * `flags` String[] (optional) - Control specific states and behaviors of the
     button. By default, it is `['enabled']`.
 
 The `flags` is an array that can include following `String`s:

docs/api/cookies.md

@@ -79,15 +79,15 @@ with `callback(error, cookies)` on complete.
 
 * `details` Object
   * `url` String - The url to associate the cookie with.
-  * `name` String - (optional) The name of the cookie. Empty by default if omitted.
+  * `name` String (optional) - The name of the cookie. Empty by default if omitted.
-  * `value` String - (optional) The value of the cookie. Empty by default if omitted.
+  * `value` String (optional) - The value of the cookie. Empty by default if omitted.
-  * `domain` String - (optional) The domain of the cookie. Empty by default if omitted.
+  * `domain` String (optional) - The domain of the cookie. Empty by default if omitted.
-  * `path` String - (optional) The path of the cookie. Empty by default if omitted.
+  * `path` String (optional) - The path of the cookie. Empty by default if omitted.
-  * `secure` Boolean - (optional) Whether the cookie should be marked as Secure. Defaults to
+  * `secure` Boolean (optional) - Whether the cookie should be marked as Secure. Defaults to
     false.
-  * `httpOnly` Boolean - (optional) Whether the cookie should be marked as HTTP only.
+  * `httpOnly` Boolean (optional) - Whether the cookie should be marked as HTTP only.
     Defaults to false.
-  * `expirationDate` Double -	(optional) The expiration date of the cookie as the number of
+  * `expirationDate` Double (optional) - The expiration date of the cookie as the number of
     seconds since the UNIX epoch. If omitted then the cookie becomes a session
     cookie and will not be retained between sessions.
 * `callback` Function

docs/api/dialog.md

@@ -32,7 +32,7 @@ The `dialog` module has the following methods:
   * `buttonLabel` String (optional) - Custom label for the confirmation button, when
     left empty the default label will be used.
   * `filters` [FileFilter[]](structures/file-filter.md) (optional)
-  * `properties` String[] - (optional) - Contains which features the dialog should use, can
+  * `properties` String[] (optional) - Contains which features the dialog should use, can
     contain `openFile`, `openDirectory`, `multiSelections`, `createDirectory`
     and `showHiddenFiles`.
 * `callback` Function (optional)
@@ -99,7 +99,7 @@ will be passed via `callback(filename)`
   * `type` String (optional) - Can be `"none"`, `"info"`, `"error"`, `"question"` or
   `"warning"`. On Windows, "question" displays the same icon as "info", unless
   you set an icon using the "icon" option.
-  * `buttons` String[] - (optional) - Array of texts for buttons. On Windows, an empty array
+  * `buttons` String[] (optional) - Array of texts for buttons. On Windows, an empty array
     will result in one button labeled "OK".
   * `defaultId` Integer (optional) - Index of the button in the buttons array which will
     be selected by default when the message box opens.

docs/api/menu-item.md

@@ -9,31 +9,31 @@ See [`Menu`](menu.md) for examples.
 ### `new MenuItem(options)`
 
 * `options` Object
-  * `click` Function - (optional) 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 - (optional) 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 - (optional) Can be `normal`, `separator`, `submenu`, `checkbox` or
+  * `type` String (optional) - Can be `normal`, `separator`, `submenu`, `checkbox` or
     `radio`.
   * `label` String - (optional)
   * `sublabel` String - (optional)
-  * `accelerator` [Accelerator](accelerator.md) - (optional)
+  * `accelerator` [Accelerator](accelerator.md) (optional)
-  * `icon` ([NativeImage](native-image.md) | String) - (optional)
+  * `icon` ([NativeImage](native-image.md) | String) (optional)
-  * `enabled` Boolean - (optional) 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 - (optional) If false, the menu item will be entirely hidden.
+  * `visible` Boolean (optional) - If false, the menu item will be entirely hidden.
-  * `checked` Boolean - (optional) Should only be specified for `checkbox` or `radio` type
+  * `checked` Boolean (optional) - Should only be specified for `checkbox` or `radio` type
     menu items.
-  * `submenu` (MenuItemConstructorOptions[] | Menu) - (optional) Should be specified for `submenu` type menu items. If
+  * `submenu` (MenuItemConstructorOptions[] | 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 - (optional) 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 - (optional) 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/cookie.md

@@ -2,13 +2,13 @@
 
 * `name` String - The name of the cookie.
 * `value` String - The value of the cookie.
-* `domain` String - (optional) The domain of the cookie.
+* `domain` String (optional) - The domain of the cookie.
-* `hostOnly` Boolean - (optional) Whether the cookie is a host-only cookie.
+* `hostOnly` Boolean (optional) - Whether the cookie is a host-only cookie.
-* `path` String - (optional) The path of the cookie.
+* `path` String (optional) - The path of the cookie.
-* `secure` Boolean - (optional) Whether the cookie is marked as secure.
+* `secure` Boolean (optional) - Whether the cookie is marked as secure.
-* `httpOnly` Boolean - (optional) Whether the cookie is marked as HTTP only.
+* `httpOnly` Boolean (optional) - Whether the cookie is marked as HTTP only.
-* `session` Boolean - (optional) Whether the cookie is a session cookie or a persistent
+* `session` Boolean (optional) - Whether the cookie is a session cookie or a persistent
   cookie with an expiration date.
-* `expirationDate` Double - (optional) The expiration date of the cookie as
+* `expirationDate` Double (optional) - The expiration date of the cookie as
   the number of seconds since the UNIX epoch. Not provided for session
   cookies.

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

@@ -1,6 +1,6 @@
 # JumpListCategory Object
 
-* `type` String - (optional) One of the following:
+* `type` String (optional) - One of the following:
   * `tasks` - Items in this category will be placed into the standard `Tasks`
     category. There can be only one such category, and it will always be
     displayed at the bottom of the Jump List.
@@ -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 - (optional) 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[] - (optional) 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

@@ -1,28 +1,28 @@
 # JumpListItem Object
 
-* `type` String - (optional) One of the following:
+* `type` String (optional) - One of the following:
   * `task` - A task will launch an app with specific arguments.
   * `separator` - Can be used to separate items in the standard `Tasks`
     category.
   * `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 - (optional) 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 - (optional) 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 - (optional) 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 - (optional) 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 - (optional) 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 - (optional) The absolute path to an icon to be displayed in a
+* `iconPath` String (optional) - The absolute path to an icon to be displayed in a
   Jump List, which can be an arbitrary resource file that contains an icon
   (e.g. `.ico`, `.exe`, `.dll`). You can usually specify `process.execPath` to
   show the program icon.
-* `iconIndex` Number - (optional) The index of the icon in the resource file. If a
+* `iconIndex` Number (optional) - The index of the icon in the resource file. If a
   resource file contains multiple icons this value can be used to specify the
   zero-based index of the icon that should be displayed for this task. If a
   resource file contains only one icon, this property should be set to zero.

docs/api/structures/thumbar-button.md

@@ -4,7 +4,7 @@
   toolbar.
 * `click` Function
 * `tooltip` String (optional) - The text of the button's tooltip.
-* `flags` String[] - (optional) - Control specific states and behaviors of the
+* `flags` String[] (optional) - Control specific states and behaviors of the
   button. By default, it is `['enabled']`.
 
 The `flags` is an array that can include following `String`s:

docs/styleguide.md

@@ -148,8 +148,8 @@ The methods chapter must be in the following form:
 ```markdown
 ### `objectName.methodName(required[, optional]))`
 
-* `required` String
+* `required` String - A parameter description.
-* `optional` Integer (optional)
+* `optional` Integer (optional) - Another parameter description.
 
 ...
 ```
@@ -187,7 +187,7 @@ denoted using a space-delimited italicized list following the datatype. Values
 can be `macOS`, `Windows`, or `Linux`.
 
 ```markdown
-* `animate` Boolean (optional) _macOS_ _Windows_
+* `animate` Boolean (optional) _macOS_ _Windows_ - Animate the thing.
 ```
 
 `Array` type arguments must specify what elements the array may include in