add documentation for editorKey prop (#1087)

* better description for polyfilling Draft in quickstart installation docs

just one of those things that i didn't pay much mind to until i was
trying to isolate a bug i'm having in ie that i'm testing using a c-r-a
sandbox.

* fixed git repo url in docs/sever readme

* add more detailed comments around editorKey prop

* add reference docs for editorKey prop in `<Editor />`

docs/APIReference-Editor.md

@@ -137,6 +137,23 @@ Default is `false`.
 These props allow you to set accessibility properties on your editor. See
 [DraftEditorProps](https://github.com/facebook/draft-js/blob/master/src/component/base/DraftEditorProps.js) for the exhaustive list of supported attributes.
 
+#### editorKey
+```
+editorKey?: string
+```
+
+You probably won't set `editorKey` on an `<Editor />` manually unless you're
+rendering a Draft component serverside. If you _are_, you must set this prop
+to avoid server/client mismatches.
+
+If the key is not set, it is generated automatically when the component
+renders and assigned as a prop of the Editor's `<DraftEditorContents />`
+component.
+
+If you _do_ set this prop, the key should be unique _per-editor_, as it is
+used to determine if styles should be preserved when pasting text within an
+editor.
+
 ### Cancelable Handlers (Optional)
 
 These prop functions are provided to allow custom event handling for a small

docs/Advanced-Topics-Issues-and-Pitfalls.md

@@ -77,4 +77,35 @@ input methods, most significantly Korean input.
 
 ### Polyfills
 
-Some of Draft's code and that of its dependencies make use of ES2015 language features. Syntax features like `class` are compiled away via Babel, but new polyfillable APIs are left intact. One example of this is `String.prototype.startsWith`. As a result, it is expected that your browser supports these APIs, either natively or with the assistance of a polyfill. One such polyfill is [es6-shim](https://github.com/es-shims/es6-shim), which we are using in our examples.
+Some of Draft's code and that of its dependencies make use of ES2015 language
+features. Syntax features like `class` are compiled away via Babel when Draft is
+built, but it does not include polyfills for APIs now included in many modern
+browsers (for instance: `String.prototype.startsWith`). We expect your browser
+supports these APIs natively or with the assistance of a polyfill. One such
+polyfill is [es6-shim](https://github.com/es-shims/es6-shim), which we use in
+many examples but you are free to use [babel-
+polyfill](https://babeljs.io/docs/usage/polyfill/) if that's more your scene.
+
+When using either polyfill/shim, you should include it as early as possibly in
+your application's entrypoint (at the very minimum, before you import Draft).
+For instance, using [create-react-app](https://github.com/facebookincubator
+/create-react-app) and targeting ie11, `src/index.js` is probably a good spot to
+import your polyfill:
+
+**src/index.js**
+
+```
+import 'babel-polyfill';
+// or
+import 'es6-shim';
+
+import React from 'react';
+import ReactDOM from 'react-dom';
+import App from './App';
+import './index.css';
+
+ReactDOM.render(
+  <App />,
+  document.getElementById('root')
+);
+```

docs/Overview.md

@@ -17,12 +17,24 @@ Draft.js was introduced at [React.js Conf](http://conf.reactjs.com/) in February
 
 ### Installation
 
-Currently Draft.js is distributed via npm. It depends on React and React DOM which must also be installed.
+Draft.js is distributed via npm. It depends on React and React DOM which must also be installed.
 
 ```sh
 npm install --save draft-js react react-dom
+# or alternately
+yarn add draft-js react react-dom
 ```
 
+Draft.js uses some modern ecmascript features which are not available to IE11 and not part of create-react-app's default babel config. If you're running into problems out-of-the-box try installing a shim or polyfill alongside Draft.
+
+```sh
+npm install --save draft-js react react-dom babel-polyfill
+# or
+yarn add draft-js react react-dom es6-shim
+```
+
+Learn more about [using a shim with Draft](/docs/advanced-topics-issues-and-pitfalls.html#polyfills).
+
 ### API Changes Notice
 
 Before getting started, please be aware that we recently changed the API of

src/component/base/DraftEditorProps.js

@@ -36,7 +36,13 @@ export type DraftEditorProps = {
   editorState: EditorState,
   onChange: (editorState: EditorState) => void,
 
-  // specify whether using ssr
+  // specify editorKey when rendering serverside. If you do not set this prop
+  // react will complain that there is a server/client mismatch because Draft
+  // will generate a random editorKey when rendering in each context. The key
+  // is used to figure out if content is being pasted within a draft block to
+  // better apply formatting and styles.  If two editors share the same key &
+  // `stripPastedStyles` is false, draft will assume both editors share their
+  // styling and formatting when re-applying styles.
   editorKey?: string,
 
   placeholder?: string,

website/README.md

@@ -21,7 +21,7 @@ First setup your environment by having two folders, one `draft` and one `draft-g
 
 ```
 cd ../../
-git clone [email protected]:facebook/draft.git draft-gh-pages
+git clone [email protected]:facebook/draft-js.git draft-gh-pages
 cd draft-gh-pages
 git checkout origin/gh-pages
 git checkout -b gh-pages