From 955ae78e33ab675fb82909c8b37d7d87f1c75a25 Mon Sep 17 00:00:00 2001
From: Jessica Lord <jlord@github.com>
Date: Fri, 28 Aug 2015 23:21:09 -0700
Subject: [PATCH] Standardize window-open

---
 docs/api/window-open.md | 35 +++++++++++++++++++----------------
 1 file changed, 19 insertions(+), 16 deletions(-)

diff --git a/docs/api/window-open.md b/docs/api/window-open.md
index fa10b2e7d055..c574d5d036ee 100644
--- a/docs/api/window-open.md
+++ b/docs/api/window-open.md
@@ -1,22 +1,22 @@
-# `window.open` function
+# The `window.open` function
 
-When `window.open` is called to create a new window in web page, a new instance
-of `BrowserWindow` will be created for the `url`, and a proxy will be returned
+When `window.open` is called to create a new window in a web page, a new instance
+of `BrowserWindow` will be created for the `url` and a proxy will be returned
 to `window.open` to let the page have limited control over it.
 
-The proxy only has some limited standard functionality implemented to be
-compatible with traditional web pages, for full control of the created window
+The proxy has limited standard functionality implemented to be
+compatible with traditional web pages. For full control of the new window
 you should create a `BrowserWindow` directly.
 
-## window.open(url, [frameName[, features]])
+### `window.open(url[, frameName][, features])`
 
 * `url` String
-* `frameName` String
-* `features` String
+* `frameName` String (optional)
+* `features` String (optional)
 
 Creates a new window and returns an instance of `BrowserWindowProxy` class.
 
-## window.opener.postMessage(message, targetOrigin)
+### `window.opener.postMessage(message, targetOrigin)`
 
 * `message` String
 * `targetOrigin` String
@@ -26,29 +26,32 @@ origin preference.
 
 ## Class: BrowserWindowProxy
 
-### BrowserWindowProxy.blur()
+The `BrowserWindowProxy` object is returned from `window.open` and provides
+limited functionality with the child window.
+
+### `BrowserWindowProxy.blur()`
 
 Removes focus from the child window.
 
-### BrowserWindowProxy.close()
+### `BrowserWindowProxy.close()`
 
 Forcefully closes the child window without calling its unload event.
 
-### BrowserWindowProxy.closed
+### `BrowserWindowProxy.closed`
 
 Set to true after the child window gets closed.
 
-### BrowserWindowProxy.eval(code)
+### `BrowserWindowProxy.eval(code)`
 
 * `code` String
 
 Evaluates the code in the child window.
 
-### BrowserWindowProxy.focus()
+### `BrowserWindowProxy.focus()`
 
 Focuses the child window (brings the window to front).
 
-### BrowserWindowProxy.postMessage(message, targetOrigin)
+### `BrowserWindowProxy.postMessage(message, targetOrigin)`
 
 * `message` String
 * `targetOrigin` String
@@ -57,4 +60,4 @@ Sends a message to the child window with the specified origin or `*` for no
 origin preference.
 
 In addition to these methods, the child window implements `window.opener` object
-with no properties and a single method:
+with no properties and a single method.