Merge pull request #7339 from electron/document-return-values

Document the return values of all methods in the docs

docs/api/app.md

@@ -357,7 +357,7 @@ app.exit(0)
 
 ### `app.isReady()`
 
-Returns `true` if Electron has finished initializing, `false` otherwise.
+Returns `Boolean` - `true` if Electron has finished initializing, `false` otherwise.
 
 ### `app.focus()`
 
@@ -375,13 +375,13 @@ them.
 
 ### `app.getAppPath()`
 
-Returns the current application directory.
+Returns `String` - The current application directory.
 
 ### `app.getPath(name)`
 
 * `name` String
 
-Retrieves a path to a special directory or file associated with `name`. On
+Returns `String` - A path to a special directory or file associated with `name`. On
 failure an `Error` is thrown.
 
 You can request the following paths by the name:
@@ -421,13 +421,13 @@ directory. If you want to change this location, you have to override the
 
 ### `app.getVersion()`
 
-Returns the version of the loaded application. If no version is found in the
+Returns `String` - The version of the loaded application. If no version is found in the
 application's `package.json` file, the version of the current bundle or
 executable is returned.
 
 ### `app.getName()`
 
-Returns the current application's name, which is the name in the application's
+Returns `String` - The current application's name, which is the name in the application's
 `package.json` file.
 
 Usually the `name` field of `package.json` is a short lowercased name, according
@@ -443,7 +443,7 @@ Overrides the current application's name.
 
 ### `app.getLocale()`
 
-Returns the current application locale. Possible return values are documented
+Returns `String` - The current application locale. Possible return values are documented
 [here](locales.md).
 
 **Note:** When distributing your packaged app, you have to also ship the
@@ -507,6 +507,8 @@ Returns `true` when the call succeeded, otherwise returns `false`.
 * `path` String (optional) _Windows_ - Defaults to `process.execPath`
 * `args` Array (optional) _Windows_ - Defaults to an empty array
 
+Returns `Boolean`
+
 This method checks if the current executable is the default handler for a protocol
 (aka URI scheme). If so, it will return true. Otherwise, it will return false.
 
@@ -548,8 +550,7 @@ Returns `true` when the call succeeded, otherwise returns `false`.
 
 ### `app.getJumpListSettings()` _Windows_
 
-Returns an Object with the following properties:
-
+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]).
@@ -759,7 +760,7 @@ is eligible for [Handoff][handoff] to another device afterward.
 
 ### `app.getCurrentActivityType()` _macOS_
 
-Returns the type of the currently running activity.
+Returns `String` - The type of the currently running activity.
 
 ### `app.setAppUserModelId(id)` _Windows_
 
@@ -799,16 +800,15 @@ for more information please read [Desktop Environment Integration][unity-require
 
 ### `app.getBadgeCount()` _Linux_ _macOS_
 
-Returns the current value displayed in the counter badge.
+Returns `Integer` - The current value displayed in the counter badge.
 
 ### `app.isUnityRunning()` _Linux_
 
-Returns whether current desktop environment is Unity launcher.
+Returns `Boolean` - Whether the current desktop environment is Unity launcher.
 
 ### `app.getLoginItemSettings()` _macOS_ _Windows_
 
-Return an Object with the login item settings of the app.
-
+Returns `Object`:
 * `openAtLogin` Boolean - `true` if the app is set to open at login.
 * `openAsHidden` Boolean - `true` if the app is set to open as hidden at login.
   This setting is only supported on macOS.
@@ -837,7 +837,7 @@ Set the app's login item settings.
 
 ### `app.isAccessibilitySupportEnabled()` _macOS_ _Windows_
 
-Returns a `Boolean`, `true` if Chrome's accessibility support is enabled,
+Returns `Boolean` - `true` if Chrome's accessibility support is enabled,
 `false` otherwise. This API will return `true` if the use of assistive
 technologies, such as screen readers, has been detected. See
 https://www.chromium.org/developers/design-documents/accessibility for more
@@ -896,7 +896,7 @@ Sets the string to be displayed in the dock’s badging area.
 
 ### `app.dock.getBadge()` _macOS_
 
-Returns the badge string of the dock.
+Returns `String` - The badge string of the dock.
 
 ### `app.dock.hide()` _macOS_
 
@@ -908,7 +908,7 @@ Shows the dock icon.
 
 ### `app.dock.isVisible()` _macOS_
 
-Returns whether the dock icon is visible.
+Returns `Boolean` - Whether the dock icon is visible.
 The `app.dock.show()` call is asynchronous so this method might not
 return true immediately after that call.
 

docs/api/auto-updater.md

@@ -104,7 +104,7 @@ Sets the `url` and initialize the auto updater.
 
 ### `autoUpdater.getFeedURL()`
 
-Returns the current update feed URL.
+Returns `String` - The current update feed URL.
 
 ### `autoUpdater.checkForUpdates()`
 

docs/api/browser-window.md

@@ -467,23 +467,23 @@ The `BrowserWindow` class has the following static methods:
 
 #### `BrowserWindow.getAllWindows()`
 
-Returns an array of all opened browser windows.
+Returns `BrowserWindow[]` - An array of all opened browser windows.
 
 #### `BrowserWindow.getFocusedWindow()`
 
-Returns the window that is focused in this application, otherwise returns `null`.
+Returns `BrowserWindow` - The window that is focused in this application, otherwise returns `null`.
 
 #### `BrowserWindow.fromWebContents(webContents)`
 
 * `webContents` [WebContents](web-contents.md)
 
-Find a window according to the `webContents` it owns.
+Returns `BrowserWindow` - The window that owns the given `webContents`.
 
 #### `BrowserWindow.fromId(id)`
 
 * `id` Integer
 
-Find a window according to its ID.
+Returns `BrowserWindow` - The window with the given `id`.
 
 #### `BrowserWindow.addDevToolsExtension(path)`
 
@@ -512,7 +512,7 @@ is emitted.
 
 #### `BrowserWindow.getDevToolsExtensions()`
 
-Returns an Object where the keys are the extension names and each value is
+Returns `Object` - The keys are the extension names and each value is
 an Object containing `name` and `version` properties.
 
 To check if a DevTools extension is installed you can run the following:
@@ -540,7 +540,7 @@ win.loadURL('https://github.com')
 
 #### `win.webContents`
 
-The `WebContents` object this window owns. All web page related events and
+A `WebContents` object this window owns. All web page related events and
 operations will be done via it.
 
 See the [`webContents` documentation](web-contents.md) for its methods and
@@ -548,7 +548,7 @@ events.
 
 #### `win.id`
 
-The unique ID of the window.
+A `Integer` representing the unique ID of the window.
 
 ### Instance Methods
 
@@ -579,11 +579,11 @@ Removes focus from the window.
 
 #### `win.isFocused()`
 
-Returns a boolean, whether the window is focused.
+Returns `Boolean` - Whether the window is focused.
 
 #### `win.isDestroyed()`
 
-Returns a boolean, whether the window is destroyed.
+Returns `Boolean` - Whether the window is destroyed.
 
 #### `win.show()`
 
@@ -599,11 +599,11 @@ Hides the window.
 
 #### `win.isVisible()`
 
-Returns a boolean, whether the window is visible to the user.
+Returns `Boolean` - Whether the window is visible to the user.
 
 #### `win.isModal()`
 
-Returns a boolean, whether current window is a modal window.
+Returns `Boolean` - Whether current window is a modal window.
 
 #### `win.maximize()`
 
@@ -615,7 +615,7 @@ Unmaximizes the window.
 
 #### `win.isMaximized()`
 
-Returns a boolean, whether the window is maximized.
+Returns `Boolean` - Whether the window is maximized.
 
 #### `win.minimize()`
 
@@ -628,7 +628,7 @@ Restores the window from minimized state to its previous state.
 
 #### `win.isMinimized()`
 
-Returns a boolean, whether the window is minimized.
+Returns `Boolean` - Whether the window is minimized.
 
 #### `win.setFullScreen(flag)`
 
@@ -638,7 +638,7 @@ Sets whether the window should be in fullscreen mode.
 
 #### `win.isFullScreen()`
 
-Returns a boolean, whether the window is in fullscreen mode.
+Returns `Boolean` - Whether the window is in fullscreen mode.
 
 #### `win.setAspectRatio(aspectRatio[, extraSize])` _macOS_
 
@@ -676,7 +676,11 @@ Resizes and moves the window to `width`, `height`, `x`, `y`.
 
 #### `win.getBounds()`
 
-Returns an object that contains window's width, height, x and y values.
+Returns `Object`:
+* `width` Integer
+* `height` Integer
+* `x` Integer
+* `y` Integer
 
 #### `win.setContentBounds(options[, animate])`
 
@@ -692,6 +696,12 @@ Resizes and moves the window's client area (e.g. the web page) to
 
 #### `win.getContentBounds()`
 
+Returns `Object`:
+* `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.
 
@@ -705,7 +715,7 @@ Resizes the window to `width` and `height`.
 
 #### `win.getSize()`
 
-Returns an array that contains window's width and height.
+Returns `Integer[]` - Contains the window's width and height.
 
 #### `win.setContentSize(width, height[, animate])`
 
@@ -717,7 +727,7 @@ Resizes the window's client area (e.g. the web page) to `width` and `height`.
 
 #### `win.getContentSize()`
 
-Returns an array that contains window's client area's width and height.
+Returns `Integer[]` - Contains the window's client area's width and height.
 
 #### `win.setMinimumSize(width, height)`
 
@@ -728,7 +738,7 @@ Sets the minimum size of window to `width` and `height`.
 
 #### `win.getMinimumSize()`
 
-Returns an array that contains window's minimum width and height.
+Returns `Integer[]` - Contains the window's minimum width and height.
 
 #### `win.setMaximumSize(width, height)`
 
@@ -739,7 +749,7 @@ Sets the maximum size of window to `width` and `height`.
 
 #### `win.getMaximumSize()`
 
-Returns an array that contains window's maximum width and height.
+Returns `Integer[]` - Contains the window's maximum width and height.
 
 #### `win.setResizable(resizable)`
 
@@ -749,7 +759,7 @@ Sets whether the window can be manually resized by user.
 
 #### `win.isResizable()`
 
-Returns whether the window can be manually resized by user.
+Returns `Boolean` - Whether the window can be manually resized by user.
 
 #### `win.setMovable(movable)` _macOS_ _Windows_
 
@@ -759,8 +769,9 @@ Sets whether the window can be moved by user. On Linux does nothing.
 
 #### `win.isMovable()` _macOS_ _Windows_
 
-Returns whether the window can be moved by user. On Linux always returns
-`true`.
+Returns `Boolean` - Whether the window can be moved by user.
+
+On Linux always returns `true`.
 
 #### `win.setMinimizable(minimizable)` _macOS_ _Windows_
 
@@ -771,8 +782,9 @@ nothing.
 
 #### `win.isMinimizable()` _macOS_ _Windows_
 
-Returns whether the window can be manually minimized by user. On Linux always
-returns `true`.
+Returns `Boolean` - Whether the window can be manually minimized by user
+
+On Linux always returns `true`.
 
 #### `win.setMaximizable(maximizable)` _macOS_ _Windows_
 
@@ -783,8 +795,9 @@ nothing.
 
 #### `win.isMaximizable()` _macOS_ _Windows_
 
-Returns whether the window can be manually maximized by user. On Linux always
-returns `true`.
+Returns `Boolean` - Whether the window can be manually maximized by user.
+
+On Linux always returns `true`.
 
 #### `win.setFullScreenable(fullscreenable)`
 
@@ -795,7 +808,7 @@ maximizes the window.
 
 #### `win.isFullScreenable()`
 
-Returns whether the maximize/zoom window button toggles fullscreen mode or
+Returns `Boolean` - Whether the maximize/zoom window button toggles fullscreen mode or
 maximizes the window.
 
 #### `win.setClosable(closable)` _macOS_ _Windows_
@@ -806,8 +819,9 @@ Sets whether the window can be manually closed by user. On Linux does nothing.
 
 #### `win.isClosable()` _macOS_ _Windows_
 
-Returns whether the window can be manually closed by user. On Linux always
-returns `true`.
+Returns `Boolean` - Whether the window can be manually closed by user.
+
+On Linux always returns `true`.
 
 #### `win.setAlwaysOnTop(flag)`
 
@@ -819,7 +833,7 @@ can not be focused on.
 
 #### `win.isAlwaysOnTop()`
 
-Returns whether the window is always on top of other windows.
+Returns `Boolean` - Whether the window is always on top of other windows.
 
 #### `win.center()`
 
@@ -835,7 +849,7 @@ Moves window to `x` and `y`.
 
 #### `win.getPosition()`
 
-Returns an array that contains window's current position.
+Returns `Integer[]` - Contains the window's current position.
 
 #### `win.setTitle(title)`
 
@@ -845,7 +859,7 @@ Changes the title of native window to `title`.
 
 #### `win.getTitle()`
 
-Returns the title of the native window.
+Returns `String` - The title of the native window.
 
 **Note:** The title of web page can be different from the title of the native
 window.
@@ -887,11 +901,11 @@ Enters or leaves the kiosk mode.
 
 #### `win.isKiosk()`
 
-Returns whether the window is in kiosk mode.
+Returns `Boolean` - Whether the window is in kiosk mode.
 
 #### `win.getNativeWindowHandle()`
 
-Returns the platform-specific handle of the window as `Buffer`.
+Returns `Buffer` - The platform-specific handle of the window.
 
 The native type of the handle is `HWND` on Windows, `NSView*` on macOS, and
 `Window` (`unsigned long`) on Linux.
@@ -908,7 +922,7 @@ the message is received in the WndProc.
 
 * `message` Integer
 
-Returns `true` or `false` depending on whether the message is hooked.
+Returns `Boolean` - `true` or `false` depending on whether the message is hooked.
 
 #### `win.unhookWindowMessage(message)` _Windows_
 
@@ -929,7 +943,7 @@ will show in window's title bar.
 
 #### `win.getRepresentedFilename()` _macOS_
 
-Returns the pathname of the file the window represents.
+Returns `String` - The pathname of the file the window represents.
 
 #### `win.setDocumentEdited(edited)` _macOS_
 
@@ -940,7 +954,7 @@ bar will become gray when set to `true`.
 
 #### `win.isDocumentEdited()` _macOS_
 
-Whether the window's document has been edited.
+Whether `Boolean` - Whether the window's document has been edited.
 
 #### `win.focusOnWebView()`
 
@@ -1034,7 +1048,9 @@ nothing.
 
 #### `win.hasShadow()` _macOS_
 
-Returns whether the window has a shadow. On Windows and Linux always returns
+Returns `Boolean` - Whether the window has a shadow.
+
+On Windows and Linux always returns
 `true`.
 
 #### `win.setThumbarButtons(buttons)` _Windows_
@@ -1115,7 +1131,7 @@ hide it immediately.
 
 #### `win.isMenuBarAutoHide()`
 
-Returns whether menu bar automatically hides itself.
+Returns `Boolean` - Whether menu bar automatically hides itself.
 
 #### `win.setMenuBarVisibility(visible)`
 
@@ -1126,7 +1142,7 @@ can still bring up the menu bar by pressing the single `Alt` key.
 
 #### `win.isMenuBarVisible()`
 
-Returns whether the menu bar is visible.
+Returns `Boolean` - Whether the menu bar is visible.
 
 #### `win.setVisibleOnAllWorkspaces(visible)`
 
@@ -1138,7 +1154,7 @@ Sets whether the window should be visible on all workspaces.
 
 #### `win.isVisibleOnAllWorkspaces()`
 
-Returns whether the window is visible on all workspaces.
+Returns `Boolean` - Whether the window is visible on all workspaces.
 
 **Note:** This API always returns false on Windows.
 
@@ -1178,8 +1194,8 @@ current window into a top-level window.
 
 #### `win.getParentWindow()`
 
-Returns the parent window.
+Returns `BrowserWindow` - The parent window.
 
 #### `win.getChildWindows()`
 
-Returns all child windows.
+Returns `BrowserWindow[]` - All child windows.

docs/api/clipboard.md

@@ -28,7 +28,7 @@ The `clipboard` module has the following methods:
 
 * `type` String (optional)
 
-Returns the content in the clipboard as plain text.
+Returns `String` - The content in the clipboard as plain text.
 
 ### `clipboard.writeText(text[, type])`
 
@@ -41,7 +41,7 @@ Writes the `text` into the clipboard as plain text.
 
 * `type` String (optional)
 
-Returns the content in the clipboard as markup.
+Returns `String` - The content in the clipboard as markup.
 
 ### `clipboard.writeHTML(markup[, type])`
 
@@ -54,7 +54,7 @@ Writes `markup` to the clipboard.
 
 * `type` String (optional)
 
-Returns the content in the clipboard as a [NativeImage](native-image.md).
+Returns `NativeImage` - The content in the clipboard as a [NativeImage](native-image.md).
 
 ### `clipboard.writeImage(image[, type])`
 
@@ -67,7 +67,7 @@ Writes `image` to the clipboard.
 
 * `type` String (optional)
 
-Returns the content in the clipboard as RTF.
+Returns `String` - The content in the clipboard as RTF.
 
 ### `clipboard.writeRTF(text[, type])`
 
@@ -78,6 +78,10 @@ Writes the `text` into the clipboard in RTF.
 
 ### `clipboard.readBookmark()` _macOS_ _Windows_
 
+Returns `Object`:
+* `title` String
+* `url` String
+
 Returns an Object containing `title` and `url` keys representing the bookmark in
 the clipboard. The `title` and `url` values will be empty strings when the
 bookmark is unavailable.
@@ -111,14 +115,14 @@ Clears the clipboard content.
 
 * `type` String (optional)
 
-Returns an array of supported formats for the clipboard `type`.
+Returns `String[]` - An array of supported formats for the clipboard `type`.
 
 ### `clipboard.has(data[, type])` _Experimental_
 
 * `data` String
 * `type` String (optional)
 
-Returns whether the clipboard supports the format of specified `data`.
+Returns `Boolean` - Whether the clipboard supports the format of specified `data`.
 
 ```javascript
 const {clipboard} = require('electron')
@@ -130,7 +134,7 @@ console.log(clipboard.has('<p>selection</p>'))
 * `data` String
 * `type` String (optional)
 
-Reads `data` from the clipboard.
+Returns `String` - Reads `data` from the clipboard.
 
 ### `clipboard.write(data[, type])`
 

docs/api/crash-reporter.md

@@ -50,11 +50,19 @@ crash reports.
 
 ### `crashReporter.getLastCrashReport()`
 
+Returns `Object`:
+* `date` String
+* `ID` Integer
+
 Returns the date and ID of the last crash report. If no crash reports have been
 sent or the crash reporter has not been started, `null` is returned.
 
 ### `crashReporter.getUploadedReports()`
 
+Returns `Object[]`:
+* `date` String
+* `ID` Integer
+
 Returns all uploaded crash reports. Each report contains the date and uploaded
 ID.
 

docs/api/download-item.md

@@ -82,7 +82,7 @@ routine to determine the save path(Usually prompts a save dialog).
 
 ### `downloadItem.getSavePath()`
 
-Returns the save path of the download item. This will be either the path
+Returns `String` - The save path of the download item. This will be either the path
 set via `downloadItem.setSavePath(path)` or the path selected from the shown
 save dialog.
 
@@ -92,7 +92,7 @@ Pauses the download.
 
 ### `downloadItem.isPaused()`
 
-Returns whether the download is paused.
+Returns `Boolean` - Whether the download is paused.
 
 ### `downloadItem.resume()`
 
@@ -100,7 +100,7 @@ Resumes the download that has been paused.
 
 ### `downloadItem.canResume()`
 
-Resumes whether the download can resume.
+Resumes `Boolean` - Whether the download can resume.
 
 ### `downloadItem.cancel()`
 
@@ -108,19 +108,19 @@ Cancels the download operation.
 
 ### `downloadItem.getURL()`
 
-Returns a `String` represents the origin url where the item is downloaded from.
+Returns `String` - The origin url where the item is downloaded from.
 
 ### `downloadItem.getMimeType()`
 
-Returns a `String` represents the mime type.
+Returns `String` - The files mime type.
 
 ### `downloadItem.hasUserGesture()`
 
-Returns a `Boolean` indicates whether the download has user gesture.
+Returns `Boolean` - Whether the download has user gesture.
 
 ### `downloadItem.getFilename()`
 
-Returns a `String` represents the file name of the download item.
+Returns `String` - The file name of the download item.
 
 **Note:** The file name is not always the same as the actual one saved in local
 disk. If user changes the file name in a prompted download saving dialog, the
@@ -128,21 +128,22 @@ actual name of saved file will be different.
 
 ### `downloadItem.getTotalBytes()`
 
-Returns a `Integer` represents the total size in bytes of the download item.
+Returns `Integer` - The total size in bytes of the download item.
+
 If the size is unknown, it returns 0.
 
 ### `downloadItem.getReceivedBytes()`
 
-Returns a `Integer` represents the received bytes of the download item.
+Returns `Integer` - The received bytes of the download item.
 
 ### `downloadItem.getContentDisposition()`
 
-Returns a `String` represents the Content-Disposition field from the response
+Returns `String` - The Content-Disposition field from the response
 header.
 
 ### `downloadItem.getState()`
 
-Returns current state as `String`.
+Returns `String` - The current state.
 
 Possible values are:
 

docs/api/global-shortcut.md

@@ -56,7 +56,7 @@ want applications to fight for global shortcuts.
 
 * `accelerator` [Accelerator](accelerator.md)
 
-Returns whether this application has registered `accelerator`.
+Returns `Boolean` - Whether this application has registered `accelerator`.
 
 When the accelerator is already taken by other applications, this call will
 still return `false`. This behavior is intended by operating systems, since they

docs/api/menu.md

@@ -294,7 +294,7 @@ Inserts the `menuItem` to the `pos` position of the menu.
 
 #### `menu.items`
 
-Get an array containing the menu's items.
+A MenuItem[] array containing the menu's items.
 
 ## Notes on macOS Application Menu
 

docs/api/native-image.md

@@ -114,12 +114,16 @@ an instance of the `NativeImage` class:
 
 ### `nativeImage.createEmpty()`
 
+Returns `NativeImage`
+
 Creates an empty `NativeImage` instance.
 
 ### `nativeImage.createFromPath(path)`
 
 * `path` String
 
+Returns `NativeImage`
+
 Creates a new `NativeImage` instance from a file located at `path`. This method
 returns an empty image if the `path` does not exist, cannot be read, or is not
 a valid image.
@@ -136,6 +140,8 @@ console.log(image)
 * `buffer` [Buffer][buffer]
 * `scaleFactor` Double (optional)
 
+Returns `NativeImage`
+
 Creates a new `NativeImage` instance from `buffer`. The default `scaleFactor` is
 1.0.
 
@@ -155,26 +161,26 @@ The following methods are available on instances of the `NativeImage` class:
 
 #### `image.toPNG()`
 
-Returns a [Buffer][buffer] that contains the image's `PNG` encoded data.
+Returns `Buffer` - A [Buffer][buffer] that contains the image's `PNG` encoded data.
 
 #### `image.toJPEG(quality)`
 
 * `quality` Integer (**required**) - Between 0 - 100.
 
-Returns a [Buffer][buffer] that contains the image's `JPEG` encoded data.
+Returns `Buffer` - A [Buffer][buffer] that contains the image's `JPEG` encoded data.
 
 #### `image.toBitmap()`
 
-Returns a [Buffer][buffer] that contains a copy of the image's raw bitmap pixel
+Returns `Buffer` - A [Buffer][buffer] that contains a copy of the image's raw bitmap pixel
 data.
 
 #### `image.toDataURL()`
 
-Returns the data URL of the image.
+Returns `String` - The data URL of the image.
 
 #### `image.getBitmap()`
 
-Returns a [Buffer][buffer] that contains the image's raw bitmap pixel data.
+Returns `Buffer` - A [Buffer][buffer] that contains the image's raw bitmap pixel data.
 
 The difference between `getBitmap()` and `toBitmap()` is, `getBitmap()` does not
 copy the bitmap data, so you have to use the returned Buffer immediately in
@@ -182,7 +188,7 @@ current event loop tick, otherwise the data might be changed or destroyed.
 
 #### `image.getNativeHandle()` _macOS_
 
-Returns a [Buffer][buffer] that stores C pointer to underlying native handle of
+Returns `Buffer` - A [Buffer][buffer] that stores C pointer to underlying native handle of
 the image. On macOS, a pointer to `NSImage` instance would be returned.
 
 Notice that the returned pointer is a weak pointer to the underlying native
@@ -191,11 +197,11 @@ image instead of a copy, so you _must_ ensure that the associated
 
 #### `image.isEmpty()`
 
-Returns a boolean whether the image is empty.
+Returns `Boolean` -  Whether the image is empty.
 
 #### `image.getSize()`
 
-Returns the size of the image.
+Returns `Integer[]` - The size of the image.
 
 [buffer]: https://nodejs.org/api/buffer.html#buffer_class_buffer
 
@@ -207,4 +213,4 @@ Marks the image as a template image.
 
 #### `image.isTemplateImage()`
 
-Returns a boolean whether the image is a template image.
+Returns `Boolean` - Whether the image is a template image.

docs/api/power-save-blocker.md

@@ -26,6 +26,8 @@ The `powerSaveBlocker` module has the following methods:
   * `prevent-display-sleep` - Prevent the display from going to sleep. Keeps
     system and screen active.  Example use case: playing video.
 
+Returns `Integer` - The blocker ID that is assigned to this power blocker
+
 Starts preventing the system from entering lower-power mode. Returns an integer
 identifying the power save blocker.
 
@@ -49,4 +51,4 @@ Stops the specified power save blocker.
 
 * `id` Integer - The power save blocker id returned by `powerSaveBlocker.start`.
 
-Returns a boolean whether the corresponding `powerSaveBlocker` has started.
+Returns `Boolean` - Whether the corresponding `powerSaveBlocker` has started.

docs/api/process.md

@@ -83,9 +83,7 @@ limit, whichever is lower for the current process.
 
 ### `process.getProcessMemoryInfo()`
 
-Returns an object giving memory usage statistics about the current process. Note
-that all statistics are reported in Kilobytes.
-
+Returns `Object`:
 * `workingSetSize` Integer - The amount of memory currently pinned to actual physical
   RAM.
 * `peakWorkingSetSize` Integer - The maximum amount of memory that has ever been pinned
@@ -95,11 +93,12 @@ that all statistics are reported in Kilobytes.
 * `sharedBytes` Integer - The amount of memory shared between processes, typically
   memory consumed by the Electron code itself
 
-### `process.getSystemMemoryInfo()`
-
-Returns an object giving memory usage statistics about the entire system. Note
+Returns an object giving memory usage statistics about the current process. Note
 that all statistics are reported in Kilobytes.
 
+### `process.getSystemMemoryInfo()`
+
+Returns `Object`:
 * `total` Integer - The total amount of physical memory in Kilobytes available to the
   system.
 * `free` Integer - The total amount of memory not being used by applications or disk
@@ -108,3 +107,6 @@ that all statistics are reported in Kilobytes.
   system.  _Windows_ _Linux_
 * `swapFree` Integer - The free amount of swap memory in Kilobytes available to the
   system.  _Windows_ _Linux_
+
+Returns an object giving memory usage statistics about the entire system. Note
+that all statistics are reported in Kilobytes.

docs/api/remote.md

@@ -138,22 +138,22 @@ The `remote` module has the following methods:
 
 * `module` String
 
-Returns the object returned by `require(module)` in the main process.
+Returns `Object` - The object returned by `require(module)` in the main process.
 
 ### `remote.getCurrentWindow()`
 
-Returns the [`BrowserWindow`](browser-window.md) object to which this web page
+Returns `BrowserWindow` - The [`BrowserWindow`](browser-window.md) object to which this web page
 belongs.
 
 ### `remote.getCurrentWebContents()`
 
-Returns the [`WebContents`](web-contents.md) object of this web page.
+Returns `WebContents` - The [`WebContents`](web-contents.md) object of this web page.
 
 ### `remote.getGlobal(name)`
 
 * `name` String
 
-Returns the global variable of `name` (e.g. `global[name]`) in the main
+Returns `any` - The global variable of `name` (e.g. `global[name]`) in the main
 process.
 
 ## Properties

docs/api/screen.md

@@ -106,15 +106,19 @@ The `screen` module has the following methods:
 
 ### `screen.getCursorScreenPoint()`
 
-Returns the current absolute position of the mouse pointer.
+Returns `Object`:
+* `x` Integer
+* `y` Integer
+
+The current absolute position of the mouse pointer.
 
 ### `screen.getPrimaryDisplay()`
 
-Returns the primary display.
+Returns `Display` - The primary display.
 
 ### `screen.getAllDisplays()`
 
-Returns an array of displays that are currently available.
+Returns `Display[]` - An array of displays that are currently available.
 
 ### `screen.getDisplayNearestPoint(point)`
 
@@ -122,7 +126,7 @@ Returns an array of displays that are currently available.
   * `x` Integer
   * `y` Integer
 
-Returns the display nearest the specified point.
+Returns `Display` - The display nearest the specified point.
 
 ### `screen.getDisplayMatching(rect)`
 
@@ -132,4 +136,4 @@ Returns the display nearest the specified point.
   * `width` Integer
   * `height` Integer
 
-Returns the display that most closely intersects the provided bounds.
+Returns `Display` - The display that most closely intersects the provided bounds.

docs/api/session.md

@@ -27,7 +27,7 @@ The `session` module has the following methods:
 * `options` Object
   * `cache` Boolean - Whether to enable cache.
 
-Returns a `Session` instance from `partition` string. When there is an existing
+Returns `Session` - A session instance from `partition` string. When there is an existing
 `Session` with the same `partition`, it will be returned; othewise a new
 `Session` instance will be created with `options`.
 
@@ -46,7 +46,7 @@ The `session` module has the following properties:
 
 ### `session.defaultSession`
 
-Returns the default session object of the app.
+A `Session` object, the default session object of the app.
 
 ## Class: Session
 
@@ -324,7 +324,7 @@ This doesn't affect existing `WebContents`, and each `WebContents` can use
 
 #### `ses.getUserAgent()`
 
-Returns a `String` representing the user agent for this session.
+Returns `String` - The user agent for this session.
 
 #### `ses.getBlobData(identifier, callback)`
 
@@ -332,7 +332,7 @@ Returns a `String` representing the user agent for this session.
 * `callback` Function
   * `result` Buffer - Blob data.
 
-Returns the blob data associated with the `identifier`.
+Returns `Blob` - The blob data associated with the `identifier`.
 
 ### Instance Properties
 
@@ -340,15 +340,15 @@ The following properties are available on instances of `Session`:
 
 #### `ses.cookies`
 
-Returns an instance of `Cookies` class for this session.
+A Cookies object for this session.
 
 #### `ses.webRequest`
 
-Returns an instance of `WebRequest` class for this session.
+A WebRequest object for this session.
 
 #### `ses.protocol`
 
-Returns an instance of [protocol](protocol.md) module for this session.
+A Protocol object (an instance of [protocol](protocol.md) module) for this session.
 
 ```javascript
 const {app, session} = require('electron')

docs/api/shell.md

@@ -20,15 +20,17 @@ The `shell` module has the following methods:
 
 * `fullPath` String
 
-Show the given file in a file manager. If possible, select the file. Returns
-true if the item was successfully shown, false otherwise.
+Returns `Boolean` - Whether the item was successfully shown
+
+Show the given file in a file manager. If possible, select the file.
 
 ### `shell.openItem(fullPath)`
 
 * `fullPath` String
 
-Open the given file in the desktop's default manner. Returns true if the item
-was successfully opened, false otherwise.
+Returns `Boolean` - Whether the item was successfully opened.
+
+Open the given file in the desktop's default manner.
 
 ### `shell.openExternal(url[, options])`
 
@@ -37,16 +39,18 @@ was successfully opened, false otherwise.
   * `activate` Boolean - `true` to bring the opened application to the
     foreground. The default is `true`.
 
+Returns `Boolean` - Whether an application was available to open the URL.
+
 Open the given external protocol URL in the desktop's default manner. (For
-example, mailto: URLs in the user's default mail agent.) Returns true if an
-application was available to open the URL, false otherwise.
+example, mailto: URLs in the user's default mail agent).
 
 ### `shell.moveItemToTrash(fullPath)`
 
 * `fullPath` String
 
+Returns `Boolean` - Whether the item was successfully moved to the trash
+
 Move the given file to trash and returns a boolean status for the operation.
-Returns true if the item was successfully moved to the trash, false otherwise.
 
 ### `shell.beep()`
 
@@ -76,14 +80,29 @@ Play the beep sound.
   * `appUserModelId` String (optional) - The Application User Model ID. Default
     is empty.
 
-Creates or updates a shortcut link at `shortcutPath`. On success `true` is
-returned, otherwise `false` is returned.
+Returns `Boolean` - Whether the shortcut was created successfully
+
+Creates or updates a shortcut link at `shortcutPath`.
 
 ### `shell.readShortcutLink(shortcutPath)` _Windows_
 
 * `shortcutPath` String
 
-Resolves the shortcut link at `shortcutPath`. An object is returned with the
-fields described in the `options` of `shell.writeShortcutLink`.
+Returns `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` 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`.
 
 An exception will be thrown when any error happens.

docs/api/system-preferences.md

@@ -24,11 +24,11 @@ accent color.
 
 ### `systemPreferences.isDarkMode()` _macOS_
 
-This method returns `true` if the system is in Dark Mode, and `false` otherwise.
+Returns `Boolean` - Whether the the system is in Dark Mode.
 
 ### `systemPreferences.isSwipeTrackingFromScrollEventsEnabled()` _macOS_
 
-This method returns `true` if the Swipe between pages setting is on, and `false` otherwise.
+Returns `Boolean` - Whether the Swipe between pages setting is on.
 
 ### `systemPreferences.postNotification(event, userInfo)` _macOS_
 

docs/api/tray.md

@@ -243,12 +243,12 @@ Sets the context menu for this icon.
 
 #### `tray.getBounds()` _macOS_ _Windows_
 
-Returns the `bounds` of this tray icon as `Object`.
+Returns `Object`:
+* `x` Integer
+* `y` Integer
+* `width` Integer
+* `height` Integer
 
-* `bounds` Object
-  * `x` Integer
-  * `y` Integer
-  * `width` Integer
-  * `height` Integer
+The `bounds` of this tray icon as `Object`.
 
 [event-emitter]: http://nodejs.org/api/events.html#events_class_events_eventemitter

docs/api/web-contents.md

@@ -29,19 +29,19 @@ console.log(webContents)
 
 ### `webContents.getAllWebContents()`
 
-Returns an array of all `WebContents` instances. This will contain web contents
+Returns `WebContents[]` - An array of all `WebContents` instances. This will contain web contents
 for all windows, webviews, opened devtools, and devtools extension background pages.
 
 ### `webContents.getFocusedWebContents()`
 
-Returns the web contents that is focused in this application, otherwise
+Returns `WebContents` - The web contents that is focused in this application, otherwise
 returns `null`.
 
 ### `webContents.fromId(id)`
 
 * `id` Integer
 
-Find a `WebContents` instance according to its ID.
+Returns `WebContents` - A WebContents instance with the given ID.
 
 ## Class: WebContents
 
@@ -524,7 +524,7 @@ Initiates a download of the resource at `url` without navigating. The
 
 #### `contents.getURL()`
 
-Returns URL of the current web page.
+Returns `String` - The URL of the current web page.
 
 ```javascript
 const {BrowserWindow} = require('electron')
@@ -537,28 +537,28 @@ console.log(currentURL)
 
 #### `contents.getTitle()`
 
-Returns the title of the current web page.
+Returns `String` - The title of the current web page.
 
 #### `contents.isDestroyed()`
 
-Returns a Boolean, whether the web page is destroyed.
+Returns `Boolean` - Whether the web page is destroyed.
 
 #### `contents.isFocused()`
 
-Returns a Boolean, whether the web page is focused.
+Returns `Boolean` - Whether the web page is focused.
 
 #### `contents.isLoading()`
 
-Returns whether web page is still loading resources.
+Returns `Boolean` - Whether web page is still loading resources.
 
 #### `contents.isLoadingMainFrame()`
 
-Returns whether the main frame (and not just iframes or frames within it) is
+Returns `Boolean` - Whether the main frame (and not just iframes or frames within it) is
 still loading.
 
 #### `contents.isWaitingForResponse()`
 
-Returns whether the web page is waiting for a first-response from the main
+Returns `Boolean` - Whether the web page is waiting for a first-response from the main
 resource of the page.
 
 #### `contents.stop()`
@@ -575,17 +575,17 @@ Reloads current page and ignores cache.
 
 #### `contents.canGoBack()`
 
-Returns whether the browser can go back to previous web page.
+Returns `Boolean` - Whether the browser can go back to previous web page.
 
 #### `contents.canGoForward()`
 
-Returns whether the browser can go forward to next web page.
+Returns `Boolean` - Whether the browser can go forward to next web page.
 
 #### `contents.canGoToOffset(offset)`
 
 * `offset` Integer
 
-Returns whether the web page can go to `offset`.
+Returns `Boolean` - Whether the web page can go to `offset`.
 
 #### `contents.clearHistory()`
 
@@ -613,7 +613,7 @@ Navigates to the specified offset from the "current entry".
 
 #### `contents.isCrashed()`
 
-Whether the renderer process has crashed.
+Returns `Boolean` - Whether the renderer process has crashed.
 
 #### `contents.setUserAgent(userAgent)`
 
@@ -623,7 +623,7 @@ Overrides the user agent for this web page.
 
 #### `contents.getUserAgent()`
 
-Returns a `String` representing the user agent for this web page.
+Returns `String` - The user agent for this web page.
 
 #### `contents.insertCSS(css)`
 
@@ -652,7 +652,7 @@ Mute the audio on the current web page.
 
 #### `contents.isAudioMuted()`
 
-Returns whether this page has been muted.
+Returns `Boolean` - Whether this page has been muted.
 
 #### `contents.setZoomFactor(factor)`
 
@@ -925,11 +925,11 @@ Closes the devtools.
 
 #### `contents.isDevToolsOpened()`
 
-Returns whether the devtools is opened.
+Returns `Boolean` - Whether the devtools is opened.
 
 #### `contents.isDevToolsFocused()`
 
-Returns whether the devtools view is focused .
+Returns `Boolean` - Whether the devtools view is focused .
 
 #### `contents.toggleDevTools()`
 
@@ -1126,7 +1126,7 @@ Shows pop-up dictionary that searches the selected word on the page.
 
 #### `contents.isOffscreen()`
 
-Indicates whether *offscreen rendering* is enabled.
+Returns `Boolean` - Indicates whether *offscreen rendering* is enabled.
 
 #### `contents.startPainting()`
 
@@ -1138,7 +1138,7 @@ If *offscreen rendering* is enabled and painting, stop painting.
 
 #### `contents.isPainting()`
 
-If *offscreen rendering* is enabled returns whether it is currently painting.
+Returns `Boolean` - If *offscreen rendering* is enabled returns whether it is currently painting.
 
 #### `contents.setFrameRate(fps)`
 
@@ -1149,7 +1149,7 @@ Only values between 1 and 60 are accepted.
 
 #### `contents.getFrameRate()`
 
-If *offscreen rendering* is enabled returns the current frame rate.
+Returns `Integer` - If *offscreen rendering* is enabled returns the current frame rate.
 
 #### `contents.invalidate()`
 
@@ -1160,26 +1160,26 @@ one through the `'paint'` event.
 
 #### `contents.id`
 
-The unique ID of this WebContents.
+A Integer representing the unique ID of this WebContents.
 
 #### `contents.session`
 
-Returns the [session](session.md) object used by this webContents.
+A Session object ([session](session.md)) used by this webContents.
 
 #### `contents.hostWebContents`
 
-Returns the `WebContents` that might own this `WebContents`.
+A `WebContents` that might own this `WebContents`.
 
 #### `contents.devToolsWebContents`
 
-Get the `WebContents` of DevTools for this `WebContents`.
+A `WebContents` of DevTools for this `WebContents`.
 
 **Note:** Users should never store this object because it may become `null`
 when the DevTools has been closed.
 
 #### `contents.debugger`
 
-Get the debugger instance for this webContents.
+A Debugger instance for this webContents.
 
 ## Class: Debugger
 
@@ -1223,7 +1223,7 @@ Attaches the debugger to the `webContents`.
 
 #### `debugger.isAttached()`
 
-Returns a boolean indicating whether a debugger is attached to the `webContents`.
+Returns `Boolean` - Whether a debugger is attached to the `webContents`.
 
 #### `debugger.detach()`
 

docs/api/web-frame.md

@@ -23,7 +23,7 @@ zoom percent divided by 100, so 300% = 3.0.
 
 ### `webFrame.getZoomFactor()`
 
-Returns the current zoom factor.
+Returns `Number` - The current zoom factor.
 
 ### `webFrame.setZoomLevel(level)`
 
@@ -35,7 +35,7 @@ limits of 300% and 50% of original size, respectively.
 
 ### `webFrame.getZoomLevel()`
 
-Returns the current zoom level.
+Returns `Number` - The current zoom level.
 
 ### `webFrame.setZoomLevelLimits(minimumLevel, maximumLevel)`
 
@@ -109,6 +109,43 @@ this limitation.
 
 ### `webFrame.getResourceUsage()`
 
+Returns `Object`:
+* `images` Object
+  * `count` Integer
+  * `size` Integer
+  * `liveSize` Integer
+  * `decodedSize` Integer
+  * `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/api/web-view-tag.md

@@ -257,19 +257,19 @@ e.g. the `http://` or `file://`.
 
 ### `<webview>.getURL()`
 
-Returns URL of guest page.
+Returns `String` - The URL of guest page.
 
 ### `<webview>.getTitle()`
 
-Returns the title of guest page.
+Returns `String` - The title of guest page.
 
 ### `<webview>.isLoading()`
 
-Returns a boolean whether guest page is still loading resources.
+Returns `Boolean` - Whether guest page is still loading resources.
 
 ### `<webview>.isWaitingForResponse()`
 
-Returns a boolean whether the guest page is waiting for a first-response for the
+Returns `Boolean` - Whether the guest page is waiting for a first-response for the
 main resource of the page.
 
 ### `<webview>.stop()`
@@ -286,17 +286,17 @@ Reloads the guest page and ignores cache.
 
 ### `<webview>.canGoBack()`
 
-Returns a boolean whether the guest page can go back.
+Returns `Boolean` - Whether the guest page can go back.
 
 ### `<webview>.canGoForward()`
 
-Returns a boolean whether the guest page can go forward.
+Returns `Boolean` - Whether the guest page can go forward.
 
 ### `<webview>.canGoToOffset(offset)`
 
 * `offset` Integer
 
-Returns a boolean whether the guest page can go to `offset`.
+Returns `Boolean` - Whether the guest page can go to `offset`.
 
 ### `<webview>.clearHistory()`
 
@@ -324,7 +324,7 @@ Navigates to the specified offset from the "current entry".
 
 ### `<webview>.isCrashed()`
 
-Whether the renderer process has crashed.
+Returns `Boolean` - Whether the renderer process has crashed.
 
 ### `<webview>.setUserAgent(userAgent)`
 
@@ -334,7 +334,7 @@ Overrides the user agent for the guest page.
 
 ### `<webview>.getUserAgent()`
 
-Returns a `String` representing the user agent for guest page.
+Returns `String` - The user agent for guest page.
 
 ### `<webview>.insertCSS(css)`
 
@@ -363,11 +363,11 @@ Closes the DevTools window of guest page.
 
 ### `<webview>.isDevToolsOpened()`
 
-Returns a boolean whether guest page has a DevTools window attached.
+Returns `Boolean` - Whether guest page has a DevTools window attached.
 
 ### `<webview>.isDevToolsFocused()`
 
-Returns a boolean whether DevTools window of guest page is focused.
+Returns `Boolean` - Whether DevTools window of guest page is focused.
 
 ### `<webview>.inspectElement(x, y)`
 
@@ -388,7 +388,7 @@ Set guest page muted.
 
 ### `<webview>.isAudioMuted()`
 
-Returns whether guest page has been muted.
+Returns `Boolean` - Whether guest page has been muted.
 
 ### `<webview>.undo()`
 
@@ -528,7 +528,7 @@ Shows pop-up dictionary that searches the selected word on the page.
 
 ### `<webview>.getWebContents()`
 
-Returns the [WebContents](web-contents.md) associated with this `webview`.
+Returns `WebContents` - The [WebContents](web-contents.md) associated with this `webview`.
 
 ## DOM events
 

docs/api/window-open.md

@@ -20,7 +20,7 @@ string.
 * `frameName` String (optional)
 * `features` String (optional)
 
-Creates a new window and returns an instance of `BrowserWindowProxy` class.
+Returns `BrowserWindowProxy` - Creates a new window and returns an instance of `BrowserWindowProxy` class.
 
 The `features` string follows the format of standard browser, but each feature
 has to be a field of `BrowserWindow`'s options.
@@ -86,4 +86,4 @@ The `BrowserWindowProxy` object has the following instance properties:
 
 #### `win.closed`
 
-Set to true after the child window gets closed.
+A Boolean that is set to true after the child window gets closed.

docs/styleguide.md

@@ -101,8 +101,11 @@ Using `autoUpdater` as an example:
 * Constructors must be listed with `###`-level titles.
 * [Static Methods](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes/static) must be listed under a `### Static Methods` chapter.
 * [Instance Methods](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes#Prototype_methods) must be listed under an `### Instance Methods` chapter.
+* All methods that have a return value must start their description with "Returns `[TYPE]` - Return description"
+  * If the method returns an `Object`, its structure can be specified using a colon followed by a newline then an unordered list of properties in the same style as function parameters.
 * Instance Events must be listed under an `### Instance Events` chapter.
 * Instance Properties must be listed under an `### Instance Properties` chapter.
+  * Instance properties must start with "A [Property Type] ..."
 
 Using the `Session` and `Cookies` classes as an example: