Merge pull request #7379 from electron/seperate-structs

Move reused object structures to a standard structures folder

docs/api/app.md

@@ -219,14 +219,7 @@ Returns:
 * `event` Event
 * `webContents` [WebContents](web-contents.md)
 * `url` URL
-* `certificateList` [Objects]
+* `certificateList` [Certificate[]](structures/certificate.md)
-  * `data` String - PEM encoded data
-  * `issuerName` String - Issuer's Common Name
-  * `subjectName` String - Subject's Common Name
-  * `serialNumber` String - Hex value represented string
-  * `validStart` Integer - Start date of the certificate being valid in seconds
-  * `validExpiry` Integer - End date of the certificate being valid in seconds
-  * `fingerprint` String - Fingerprint of the certificate
 * `callback` Function
 
 Emitted when a client certificate is requested.
@@ -523,7 +516,7 @@ The API uses the Windows Registry and LSCopyDefaultHandlerForURLScheme internall
 
 ### `app.setUserTasks(tasks)` _Windows_
 
-* `tasks` Array - Array of `Task` objects
+* `tasks` [Task[]](structures/task.md) - Array of `Task` objects
 
 Adds `tasks` to the [Tasks][tasks] category of the JumpList on Windows.
 
@@ -555,7 +548,7 @@ Returns `Object`:
 * `minItems` Integer - The minimum number of items that will be shown in the
   Jump List (for a more detailed description of this value see the
   [MSDN docs][JumpListBeginListMSDN]).
-* `removedItems` Array - Array of `JumpListItem` objects that correspond to
+* `removedItems` [JumpListItem[]](structures/jump-list-item.md) - Array of `JumpListItem` objects that correspond to
   items that the user has explicitly removed from custom categories in the
   Jump List. These items must not be re-added to the Jump List in the **next**
   call to `app.setJumpList()`, Windows will not display any custom category
@@ -563,7 +556,7 @@ Returns `Object`:
 
 ### `app.setJumpList(categories)` _Windows_
 
-* `categories` Array or `null` - Array of `JumpListCategory` objects.
+* `categories` [JumpListCategory[]](structures/jump-list-category.md) or `null` - Array of `JumpListCategory` objects.
 
 Sets or removes a custom Jump List for the application, and returns one of the
 following strings:
@@ -658,15 +651,21 @@ app.setJumpList([
     name: 'Tools',
     items: [
       {
-        type: 'task', title: 'Tool A',
+        type: 'task',
-        program: process.execPath, args: '--run-tool-a',
+        title: 'Tool A',
-        icon: process.execPath, iconIndex: 0,
+        program: process.execPath,
+        args: '--run-tool-a',
+        icon: process.execPath,
+        iconIndex: 0,
         description: 'Runs Tool A'
       },
       {
-        type: 'task', title: 'Tool B',
+        type: 'task',
-        program: process.execPath, args: '--run-tool-b',
+        title: 'Tool B',
-        icon: process.execPath, iconIndex: 0,
+        program: process.execPath,
+        args: '--run-tool-b',
+        icon: process.execPath,
+        iconIndex: 0,
         description: 'Runs Tool B'
       }
     ]
@@ -675,14 +674,18 @@ app.setJumpList([
   { // has no name and no type so `type` is assumed to be "tasks"
     items: [
       {
-        type: 'task', title: 'New Project',
+        type: 'task',
-        program: process.execPath, args: '--new-project',
+        title: 'New Project',
+        program: process.execPath,
+        args: '--new-project',
         description: 'Create a new project.'
       },
       { type: 'separator' },
       {
-        type: 'task', title: 'Recover Project',
+        type: 'task',
-        program: process.execPath, args: '--recover-project',
+        title: 'Recover Project',
+        program: process.execPath,
+        args: '--recover-project',
         description: 'Recover Project'
       }
     ]

docs/api/browser-window.md

@@ -664,47 +664,28 @@ the player itself we would call this function with arguments of 16/9 and
 are within the content view--only that they exist. Just sum any extra width and
 height areas you have within the overall content view.
 
-#### `win.setBounds(options[, animate])`
+#### `win.setBounds(bounds[, animate])`
 
-* `options` Object
+* `bounds` [Rectangle](structures/rectangle.md)
-  * `x` Integer
-  * `y` Integer
-  * `width` Integer
-  * `height` Integer
 * `animate` Boolean (optional) _macOS_
 
-Resizes and moves the window to `width`, `height`, `x`, `y`.
+Resizes and moves the window to the supplied bounds
 
 #### `win.getBounds()`
 
-Returns `Object`:
+Returns [`Rectangle`](structures/rectangle.md)
-* `width` Integer
-* `height` Integer
-* `x` Integer
-* `y` Integer
 
-#### `win.setContentBounds(options[, animate])`
+#### `win.setContentBounds(bounds[, animate])`
 
-* `options` Object
+* `bounds` [Rectangle](structures/rectangle.md)
-  * `x` Integer
-  * `y` Integer
-  * `width` Integer
-  * `height` Integer
 * `animate` Boolean (optional) _macOS_
 
 Resizes and moves the window's client area (e.g. the web page) to
-`width`, `height`, `x`, `y`.
+the supplied bounds.
 
 #### `win.getContentBounds()`
 
-Returns `Object`:
+Returns [`Rectangle`](structures/rectangle.md)
-* `width` Integer
-* `height` Integer
-* `x` Integer
-* `y` Integer
-
-Returns an object that contains the window's client area (e.g. the web page)
-width, height, x and y values.
 
 #### `win.setSize(width, height[, animate])`
 
@@ -967,11 +948,7 @@ Whether `Boolean` - Whether the window's document has been edited.
 
 #### `win.capturePage([rect, ]callback)`
 
-* `rect` Object (optional) - The area of the page to be captured
+* `rect` [Rectangle](structures/rectangle.md) (optional) - The bounds to capture
-  * `x` Integer
-  * `y` Integer
-  * `width` Integer
-  * `height` Integer
 * `callback` Function
 
 Same as `webContents.capturePage([rect, ]callback)`.
@@ -1060,7 +1037,9 @@ On Windows and Linux always returns
 
 #### `win.setThumbarButtons(buttons)` _Windows_
 
-* `buttons` Array
+* `buttons` [ThumbarButton[]](structures/thumbar-button.md)
+
+Returns `Boolean` - Whether the buttons were added successfully
 
 Add a thumbnail toolbar with a specified set of buttons to the thumbnail image
 of a window in a taskbar button layout. Returns a `Boolean` object indicates
@@ -1096,11 +1075,7 @@ The `flags` is an array that can include following `String`s:
 
 #### `win.setThumbnailClip(region)` _Windows_
 
-* `region` Object - Region of the window
+* `region` [Rectangle](structures/rectangle.md) - Region of the window
-  * `x` Integer - x-position of region
-  * `y` Integer - y-position of region
-  * `width` Integer - width of region
-  * `height` Integer - height of region
 
 Sets the region of the window to show as the thumbnail image displayed when
 hovering over the window in the taskbar. You can reset the thumbnail to be

docs/api/screen.md

@@ -49,23 +49,6 @@ app.on('ready', () => {
 })
 ```
 
-## The `Display` object
-
-The `Display` object represents a physical display connected to the system. A
-fake `Display` may exist on a headless system, or a `Display` may correspond to
-a remote, virtual display.
-
-* `display` object
-  * `id` Integer - Unique identifier associated with the display.
-  * `rotation` Integer - Can be 0, 90, 180, 270, represents screen rotation in
-    clock-wise degrees.
-  * `scaleFactor` Number - Output device's pixel scale factor.
-  * `touchSupport` String - Can be `available`, `unavailable`, `unknown`.
-  * `bounds` Object
-  * `size` Object
-  * `workArea` Object
-  * `workAreaSize` Object
-
 ## Events
 
 The `screen` module emits the following events:
@@ -75,7 +58,7 @@ The `screen` module emits the following events:
 Returns:
 
 * `event` Event
-* `newDisplay` Object
+* `newDisplay` [Display](structures/display.md)
 
 Emitted when `newDisplay` has been added.
 
@@ -84,7 +67,7 @@ Emitted when `newDisplay` has been added.
 Returns:
 
 * `event` Event
-* `oldDisplay` Object
+* `oldDisplay` [Display](structures/display.md)
 
 Emitted when `oldDisplay` has been removed.
 
@@ -93,7 +76,7 @@ Emitted when `oldDisplay` has been removed.
 Returns:
 
 * `event` Event
-* `display` Object
+* `display` [Display](structures/display.md)
 * `changedMetrics` String[]
 
 Emitted when one or more metrics change in a `display`. The `changedMetrics` is
@@ -130,10 +113,6 @@ Returns `Display` - The display nearest the specified point.
 
 ### `screen.getDisplayMatching(rect)`
 
-* `rect` Object
+* `rect` [Rectangle](structures/rectangle.md)
-  * `x` Integer
-  * `y` Integer
-  * `width` Integer
-  * `height` Integer
 
 Returns `Display` - The display that most closely intersects the provided bounds.

docs/api/shell.md

@@ -64,21 +64,7 @@ Play the beep sound.
   * `update` - Updates specified properties only on an existing shortcut.
   * `replace` - Overwrites an existing shortcut, fails if the shortcut doesn't
     exist.
-* `options` Object
+* `options` [ShortcutDetails](structures/shortcut-details.md)
-  * `target` String - The target to launch from this shortcut.
-  * `cwd` String (optional) - The working directory. Default
-    is empty.
-  * `args` String (optional) - The arguments to be applied to `target` when
-    launching from this shortcut. Default is empty.
-  * `description` String (optional) - The description of the shortcut. Default
-    is empty.
-  * `icon` String (optional) - The path to the icon, can be a DLL or EXE. `icon`
-    and `iconIndex` have to be set together. Default is empty, which uses the
-    target's icon.
-  * `iconIndex` Integer (optional) - The resource ID of icon when `icon` is a
-    DLL or EXE. Default is 0.
-  * `appUserModelId` String (optional) - The Application User Model ID. Default
-    is empty.
 
 Returns `Boolean` - Whether the shortcut was created successfully
 
@@ -88,20 +74,7 @@ Creates or updates a shortcut link at `shortcutPath`.
 
 * `shortcutPath` String
 
-Returns `Object`:
+Returns [`ShortcutDetails`](structures/shortcut-details.md)
-* `target` String - The target to launch from this shortcut.
-* `cwd` String (optional) - The working directory. Default is empty.
-* `args` String (optional) - The arguments to be applied to `target` when
-launching from this shortcut. Default is empty.
-* `description` String (optional) - The description of the shortcut. Default
-is empty.
-* `icon` String (optional) - The path to the icon, can be a DLL or EXE. `icon`
-and `iconIndex` have to be set together. Default is empty, which uses the
-target's icon.
-* `iconIndex` Integer (optional) - The resource ID of icon when `icon` is a
-DLL or EXE. Default is 0.
-* `appUserModelId` String (optional) - The Application User Model ID. Default
-is empty.
 
 Resolves the shortcut link at `shortcutPath`.
 

docs/api/structures/certificate.md

@@ -0,0 +1,9 @@
+# Certificate Object
+
+* `data` String - PEM encoded data
+* `issuerName` String - Issuer's Common Name
+* `subjectName` String - Subject's Common Name
+* `serialNumber` String - Hex value represented string
+* `validStart` Number - Start date of the certificate being valid in seconds
+* `validExpiry` Number - End date of the certificate being valid in seconds
+* `fingerprint` String - Fingerprint of the certificate

docs/api/structures/display.md

@@ -0,0 +1,19 @@
+# Display Object
+
+* `id` Number - Unique identifier associated with the display.
+* `rotation` Number - Can be 0, 90, 180, 270, represents screen rotation in
+  clock-wise degrees.
+* `scaleFactor` Number - Output device's pixel scale factor.
+* `touchSupport` String - Can be `available`, `unavailable`, `unknown`.
+* `bounds` [Rectangle](rectangle.md)
+* `size` Object
+  * `height` Number
+  * `width` Number
+* `workArea` [Rectangle](rectangle.md)
+* `workAreaSize` Object
+  * `height` Number
+  * `width` Number
+
+The `Display` object represents a physical display connected to the system. A
+fake `Display` may exist on a headless system, or a `Display` may correspond to
+a remote, virtual display.

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

@@ -0,0 +1,21 @@
+# JumpListCategory Object
+
+* `type` String - 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.
+  * `frequent` - Displays a list of files frequently opened by the app, the
+    name of the category and its items are set by Windows.
+  * `recent` - Displays a list of files recently opened by the app, the name
+    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
+  omitted.
+* `items` JumpListItem[] - 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`
+property set then its `type` is assumed to be `tasks`. If the `name` property
+is set but the `type` property is omitted then the `type` is assumed to be
+`custom`.

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

@@ -0,0 +1,28 @@
+# JumpListItem Object
+
+* `type` String - 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 - 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
+  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
+  only be set if `type` is `task`.
+* `title` String - 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).
+  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
+  (e.g. `.ico`, `.exe`, `.dll`). You can usually specify `process.execPath` to
+  show the program icon.
+* `iconIndex` Number - 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/memory-usage-details.md

@@ -0,0 +1,8 @@
+# MemoryUsageDetails Object
+
+* `count` Number
+* `size` Number
+* `liveSize` Number
+* `decodedSize` Number
+* `purgedSize` Number
+* `purgeableSize` Number

docs/api/structures/rectangle.md

@@ -0,0 +1,6 @@
+# Rectangle Object
+
+* `x` Number - The x coordinate of the origin of the rectangle
+* `y` Number - The y coordinate of the origin of the rectangle
+* `width` Number
+* `height` Number

docs/api/structures/shortcut-details.md

@@ -0,0 +1,15 @@
+# ShortcutDetails Object
+
+* `target` String - The target to launch from this shortcut.
+* `cwd` String (optional) - The working directory. Default is empty.
+* `args` String (optional) - The arguments to be applied to `target` when
+launching from this shortcut. Default is empty.
+* `description` String (optional) - The description of the shortcut. Default
+is empty.
+* `icon` String (optional) - The path to the icon, can be a DLL or EXE. `icon`
+and `iconIndex` have to be set together. Default is empty, which uses the
+target's icon.
+* `iconIndex` Number (optional) - The resource ID of icon when `icon` is a
+DLL or EXE. Default is 0.
+* `appUserModelId` String (optional) - The Application User Model ID. Default
+is empty.

docs/api/structures/task.md

@@ -0,0 +1,14 @@
+# Task Object
+
+* `program` String - Path of the program to execute, usually you should
+  specify `process.execPath` which opens the current program.
+* `arguments` String - The command line arguments when `program` is
+  executed.
+* `title` String - The string to be displayed in a JumpList.
+* `description` String - Description of this task.
+* `iconPath` String - The absolute path to an icon to be displayed in a
+  JumpList, which can be an arbitrary resource file that contains an icon. You
+  can usually specify `process.execPath` to show the icon of the program.
+* `iconIndex` Number - The icon index in the icon file. If an icon file
+  consists of two or more icons, set this value to identify the icon. If an
+  icon file consists of one icon, this value is 0.

docs/api/structures/thumbar-button.md

@@ -0,0 +1,21 @@
+# ThumbarButton Object
+
+* `icon` [NativeImage](../native-image.md) - The icon showing in thumbnail
+  toolbar.
+* `click` Function
+* `tooltip` String (optional) - The text of the button's tooltip.
+* `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:
+
+* `enabled` - The button is active and available to the user.
+* `disabled` - The button is disabled. It is present, but has a visual state
+  indicating it will not respond to user action.
+* `dismissonclick` - When the button is clicked, the thumbnail window closes
+  immediately.
+* `nobackground` - Do not draw a button border, use only the image.
+* `hidden` - The button is not shown to the user.
+* `noninteractive` - The button is enabled but not interactive; no pressed
+  button state is drawn. This value is intended for instances where the button
+  is used in a notification.

docs/api/tray.md

@@ -70,11 +70,7 @@ The `Tray` module emits the following events:
   * `shiftKey` Boolean
   * `ctrlKey` Boolean
   * `metaKey` Boolean
-* `bounds` Object _macOS_ _Windows_ - the bounds of tray icon.
+* `bounds` [Rectangle](structures/rectangle.md) - The bounds of tray icon
-  * `x` Integer
-  * `y` Integer
-  * `width` Integer
-  * `height` Integer
 
 Emitted when the tray icon is clicked.
 
@@ -85,11 +81,7 @@ Emitted when the tray icon is clicked.
   * `shiftKey` Boolean
   * `ctrlKey` Boolean
   * `metaKey` Boolean
-* `bounds` Object - the bounds of tray icon.
+* `bounds` [Rectangle](structures/rectangle.md) - The bounds of tray icon
-  * `x` Integer
-  * `y` Integer
-  * `width` Integer
-  * `height` Integer
 
 Emitted when the tray icon is right clicked.
 
@@ -100,11 +92,7 @@ Emitted when the tray icon is right clicked.
   * `shiftKey` Boolean
   * `ctrlKey` Boolean
   * `metaKey` Boolean
-* `bounds` Object - the bounds of tray icon
+* `bounds` [Rectangle](structures/rectangle.md) - The bounds of tray icon
-  * `x` Integer
-  * `y` Integer
-  * `width` Integer
-  * `height` Integer
 
 Emitted when the tray icon is double clicked.
 
@@ -243,11 +231,7 @@ Sets the context menu for this icon.
 
 #### `tray.getBounds()` _macOS_ _Windows_
 
-Returns `Object`:
+Returns [`Rectangle`](structures/rectangle.md)
-* `x` Integer
-* `y` Integer
-* `width` Integer
-* `height` Integer
 
 The `bounds` of this tray icon as `Object`.
 

docs/api/web-contents.md

@@ -247,14 +247,7 @@ Returns:
 * `event` Event
 * `url` URL
 * `error` String - The error code
-* `certificate` Object
+* `certificate` [Certificate](structures/certificate.md)
-  * `data` String - PEM encoded data
-  * `issuerName` String - Issuer's Common Name
-  * `subjectName` String - Subject's Common Name
-  * `serialNumber` String - Hex value represented string
-  * `validStart` Integer - Start date of the certificate being valid in seconds
-  * `validExpiry` Integer - End date of the certificate being valid in seconds
-  * `fingerprint` String - Fingerprint of the certificate
 * `callback` Function
 
 Emitted when failed to verify the `certificate` for `url`.
@@ -268,14 +261,7 @@ Returns:
 
 * `event` Event
 * `url` URL
-* `certificateList` [Objects]
+* `certificateList` Certificate[]
-  * `data` String - PEM encoded data
-  * `issuerName` String - Issuer's Common Name
-  * `subjectName` String - Subject's Common Name
-  * `serialNumber` String - Hex value represented string
-  * `validStart` Integer - Start date of the certificate being valid in seconds
-  * `validExpiry` Integer - End date of the certificate being valid in seconds
-  * `fingerprint` String - Fingerprint of the certificate
 * `callback` Function
 
 Emitted when a client certificate is requested.
@@ -479,11 +465,7 @@ app.on('ready', () => {
 Returns:
 
 * `event` Event
-* `dirtyRect` Object
+* `dirtyRect` [Rectangle](structures/rectangle.md)
-  * `x` Integer - The x coordinate on the image.
-  * `y` Integer - The y coordinate on the image.
-  * `width` Integer - The width of the dirty area.
-  * `height` Integer - The height of the dirty area.
 * `image` [NativeImage](native-image.md) - The image data of the whole frame.
 
 Emitted when a new frame is generated. Only the dirty area is passed in the
@@ -521,7 +503,7 @@ webContents.loadURL('https://github.com', options)
 
 #### `contents.downloadURL(url)`
 
-* `url` URL
+* `url` String
 
 Initiates a download of the resource at `url` without navigating. The
 `will-download` event of `session` will be triggered.
@@ -798,11 +780,7 @@ console.log(requestId)
 
 #### `contents.capturePage([rect, ]callback)`
 
-* `rect` Object (optional) - The area of the page to be captured
+* `rect` [Rectangle](structures/rectangle.md) (optional) - The area of the page to be captured
-  * `x` Integer
-  * `y` Integer
-  * `width` Integer
-  * `height` Integer
 * `callback` Function
 
 Captures a snapshot of the page within `rect`. Upon completion `callback` will

docs/api/web-frame.md

@@ -110,41 +110,11 @@ this limitation.
 ### `webFrame.getResourceUsage()`
 
 Returns `Object`:
-* `images` Object
+* `images` [MemoryUsageDetails](structures/memory-usage-details.md)
-  * `count` Integer
+* `cssStyleSheets` [MemoryUsageDetails](structures/memory-usage-details.md)
-  * `size` Integer
+* `xslStyleSheets` [MemoryUsageDetails](structures/memory-usage-details.md)
-  * `liveSize` Integer
+* `fonts` [MemoryUsageDetails](structures/memory-usage-details.md)
-  * `decodedSize` Integer
+* `other` [MemoryUsageDetails](structures/memory-usage-details.md)
-  * `purgedSize` Integer
-  * `purgeableSize` Integer
-* `cssStyleSheets` Object
-  * `count` Integer
-  * `size` Integer
-  * `liveSize` Integer
-  * `decodedSize` Integer
-  * `purgedSize` Integer
-  * `purgeableSize` Integer
-* `xslStyleSheets` Object
-  * `count` Integer
-  * `size` Integer
-  * `liveSize` Integer
-  * `decodedSize` Integer
-  * `purgedSize` Integer
-  * `purgeableSize` Integer
-* `fonts` Object
-  * `count` Integer
-  * `size` Integer
-  * `liveSize` Integer
-  * `decodedSize` Integer
-  * `purgedSize` Integer
-  * `purgeableSize` Integer
-* `other` Object
-  * `count` Integer
-  * `size` Integer
-  * `liveSize` Integer
-  * `decodedSize` Integer
-  * `purgedSize` Integer
-  * `purgeableSize` Integer
 
 Returns an object describing usage information of Blink's internal memory
 caches.

docs/tutorial/desktop-environment-integration.md

@@ -119,10 +119,12 @@ const {app, Menu} = require('electron')
 
 const dockMenu = Menu.buildFromTemplate([
   {label: 'New Window', click () { console.log('New Window') }},
-  {label: 'New Window with Settings', submenu: [
+  {label: 'New Window with Settings',
-    {label: 'Basic'},
+    submenu: [
-    {label: 'Pro'}
+      {label: 'Basic'},
-  ]},
+      {label: 'Pro'}
+    ]
+  },
   {label: 'New Command...'}
 ])
 app.dock.setMenu(dockMenu)

package.json

@@ -5,7 +5,7 @@
     "asar": "^0.11.0",
     "browserify": "^13.1.0",
     "electabul": "~0.0.4",
-    "electron-docs-linter": "1.7.1",
+    "electron-docs-linter": "^1.8.1",
     "request": "*",
     "standard": "^7.1.2",
     "standard-markdown": "^1.2.1"