diff --git a/docs/api/browser-window.md b/docs/api/browser-window.md
index b7ea92fb1351..8444412424eb 100644
--- a/docs/api/browser-window.md
+++ b/docs/api/browser-window.md
@@ -30,8 +30,8 @@ Properties `width` and `height` are required.
 
 `options` Object, properties:
 
-* `width` Integer **required** - Window's width.
-* `height` Integer **required** - Window's height.
+* `width` Integer (**required**) - Window's width.
+* `height` Integer (**required**) - Window's height.
 * `x` Integer - Window's left offset from screen.
 * `y` Integer - Window's top offset from screen.
 * `use-content-size` Boolean - The `width` and `height` would be used as web
@@ -402,12 +402,12 @@ Sets whether the window should be in fullscreen mode.
 
 Returns a boolean, whether the window is in fullscreen mode.
 
-### `win.setAspectRatio(aspectRatio[, extraSize])`
+### `win.setAspectRatio(aspectRatio[, extraSize])` _OS X_
 
 * `aspectRatio` The aspect ratio we want to maintain for some portion of the
 content view.
-* `rect` Object - The extra size to not be included in the aspect ratio to be
-maintained. Properties:
+* `extraSize` Object (optional) - The extra size not to be included while
+maintaining the aspect ratio. Properties:
   * `width` Integer
   * `height` Integer
 
@@ -589,7 +589,7 @@ __Note__: This API is only available on OS X.
 
 ### `win.openDevTools([options])`
 
-* `options` Object, optional. Properties:
+* `options` Object (optional). Properties:
   * `detach` Boolean - opens devtools in a new window
 
 Opens the developer tools.
@@ -624,7 +624,7 @@ contents.
 
 ### `win.capturePage([rect, ]callback)`
 
-* `rect` Object - The area of page to be captured, properties:
+* `rect` Object (optional)- The area of page to be captured, properties:
   * `x` Integer
   * `y` Integer
   * `width` Integer
diff --git a/docs/api/session.md b/docs/api/session.md
index b589254087fe..184d175227be 100644
--- a/docs/api/session.md
+++ b/docs/api/session.md
@@ -116,7 +116,7 @@ Clears the session’s HTTP cache.
 
 ### `session.clearStorageData([options, ]callback)`
 
-* `options` Object
+* `options` Object (optional)
   * `origin` String - Should follow `window.location.origin`’s representation
     `scheme://host:port`
   * `storages` Array - The types of storages to clear, can contain:
diff --git a/docs/api/web-contents.md b/docs/api/web-contents.md
index 19193fc32f05..fe68d8a6a6f2 100644
--- a/docs/api/web-contents.md
+++ b/docs/api/web-contents.md
@@ -161,7 +161,7 @@ See [session documentation](session.md) for this object's methods.
 ### `webContents.loadUrl(url[, options])`
 
 * `url` URL
-* `options` Object, properties:
+* `options` Object (optional). Properties:
   * `httpReferrer` String - A HTTP Referrer url
   * `userAgent` String - A user agent originating the request
 
@@ -267,7 +267,7 @@ Injects CSS into the current web page.
 ### `webContents.executeJavaScript(code[, userGesture])`
 
 * `code` String
-* `userGesture` Boolean
+* `userGesture` Boolean (optional)
 
 Evaluates `code` in page.
 
@@ -350,7 +350,7 @@ when the JS promise is rejected.
 
 ### `webContents.print([options])`
 
-`options` Object, properties:
+`options` Object (optional). Properties:
 
 * `silent` Boolean - Don't ask user for print settings, defaults to `false`
 * `printBackground` Boolean - Also prints the background color and image of
@@ -438,8 +438,9 @@ Removes the specified path from devtools workspace.
 ### `webContents.send(channel[, args...])`
 
 * `channel` String
+* `args...` (optional)
 
-Send `args..` to the web page via `channel` in an asynchronous message, the web
+Send `args...` to the web page via `channel` in an asynchronous message, the web
 page can handle it by listening to the `channel` event of the `ipc` module.
 
 An example of sending messages from the main process to the renderer process: