Update some `uppy.state` docs to align with the Stores feature.

website/src/docs/uppy.md

@@ -79,7 +79,7 @@ Metadata can also be added from a `<form>` element on your page via [Form](/docs
 <a id="onBeforeFileAdded"></a>
 ### `onBeforeFileAdded: (currentFile, files) => currentFile`
 
-A function run before a file is added to Uppy. Gets passed `(currentFile, files)` where `currentFile` is a file that is about to be added, and `files` is an object with all files that already are in Uppy. 
+A function run before a file is added to Uppy. Gets passed `(currentFile, files)` where `currentFile` is a file that is about to be added, and `files` is an object with all files that already are in Uppy.
 
 Use this function to run any number of custom checks on the selected file, or manipulating it, like optimizing a file name, for example.
 
@@ -96,8 +96,8 @@ onBeforeFileAdded: (currentFile, files) => {
 
 onBeforeFileAdded: (currentFile, files) => {
   const modifiedFile = Object.assign(
-    {}, 
-    currentFile, 
+    {},
+    currentFile,
     { name: currentFile + Date.now()
   })
   return modifiedFile
@@ -124,7 +124,7 @@ Note: it’s up to you to show a notification to the user about file not passing
 <a id="onBeforeUpload"></a>
 ### `onBeforeUpload: (files) => files`
 
-A function run before an upload begins. Gets passed `files` object with all the files that are already in Uppy. 
+A function run before an upload begins. Gets passed `files` object with all the files that are already in Uppy.
 
 Use this to check if all files or their total number match your requirements, or manipulate all the files at once before upload.
 
@@ -192,9 +192,9 @@ We are using a forked [Polyglot.js](https://github.com/airbnb/polyglot.js/blob/m
 
 ### `store: defaultStore()`
 
-The Store to use to keep track of internal state. By default, a simple object is used.
+The Store to use to keep track of internal state. By [default](/docs/stores/#DefaultStore), a simple object is used.
 
-This option can be used to plug Uppy state into an external state management library, such as Redux. Then, you can write custom views with the library that is also used by the rest of the application.
+This option can be used to plug Uppy state into an external state management library, such as [Redux](/docs/stores/#ReduxStore). Then, you can write custom views with the library that is also used by the rest of the application.
 
 <!-- TODO document store API -->
 
@@ -240,7 +240,7 @@ If `uppy.opts.autoProceed === true`, Uppy will begin uploading automatically whe
 
 ### `uppy.getFile(fileID)`
 
-A shortcut method that returns a specific file object from `uppy.state` by its `fileID`.
+Get a specific file object by its ID.
 
 ```js
 const file = uppy.getFile('uppyteamkongjpg1501851828779')
@@ -278,7 +278,7 @@ uppy.upload().then((result) => {
 
 ### `uppy.setState(patch)`
 
-Update `uppy.state`. Usually this method is called internally, but in some cases it might be useful to alter something in `uppy.state` directly.
+Update Uppy's internal state. Usually this method is called internally, but in some cases it might be useful to alter something directly, especially when implementing your own plugins.
 
 Uppy’s default state on initialization:
 
@@ -308,18 +308,18 @@ uppy.setState({
 })
 ```
 
-We don’t mutate `uppy.state`, so internally `setState` creates a new copy of state and replaces `uppy.state` with it. However, when updating values, it’s your responsibility to not mutate them, but instead create copies. See [Redux docs](http://redux.js.org/docs/recipes/UsingObjectSpreadOperator.html) for more info on this. Here’s an example from Uppy.Core that updates progress for a particular file in state:
+State in Uppy is considered to be immutable. When updating values, it’s your responsibility to not mutate them, but instead create copies. See [Redux docs](http://redux.js.org/docs/recipes/UsingObjectSpreadOperator.html) for more info on this. Here’s an example from Uppy.Core that updates progress for a particular file in state:
 
 ```js
+// We use Object.assign({}, obj) to create a copy of `obj`.
 const updatedFiles = Object.assign({}, uppy.getState().files)
-const updatedFile = Object.assign({}, updatedFiles[fileID],
-  Object.assign({}, {
-    progress: Object.assign({}, updatedFiles[fileID].progress, {
-      bytesUploaded: data.bytesUploaded,
-      bytesTotal: data.bytesTotal,
-      percentage: Math.floor((data.bytesUploaded / data.bytesTotal * 100).toFixed(2))
-    })
-  }
+// We use Object.assign({}, obj, update) to create an altered copy of `obj`.
+const updatedFile = Object.assign({}, updatedFiles[fileID], {
+  progress: Object.assign({}, updatedFiles[fileID].progress, {
+    bytesUploaded: data.bytesUploaded,
+    bytesTotal: data.bytesTotal,
+    percentage: Math.floor((data.bytesUploaded / data.bytesTotal * 100).toFixed(2))
+  })
 ))
 updatedFiles[data.id] = updatedFile
 uppy.setState({files: updatedFiles})
@@ -327,7 +327,7 @@ uppy.setState({files: updatedFiles})
 
 ### `uppy.getState()`
 
-Returns `uppy.state`, which you can also use directly.
+Returns the current state from the [Store](#store-defaultStore).
 
 ### `uppy.setFileState(fileID, state)`
 
@@ -479,7 +479,7 @@ uppy.on('complete', (result) => {
 
 ### `error`
 
-Fired when Uppy fails to upload/encode the whole upload. That error is then set to `uppy.state.error`.
+Fired when Uppy fails to upload/encode the whole upload. That error is then set to `uppy.getState().error`.
 
 ### `upload-error`