Add intro documentation to explain how state management works

For the benefit of developers who are not familiar with Redux and
Elm-style architectures, add documentation at the top of the
annotationUI module which explains how state is managed in the app.

h/static/scripts/annotation-ui.js

 'use strict';
 
 /**
- * AnnotationUI provides the central store of UI state for the application,
- * using [Redux](http://redux.js.org/).
+ * AnnotationUI is the central store of state for the sidebar application,
+ * managed using [Redux](http://redux.js.org/).
  *
- * Redux is used to provide a predictable way of updating UI state and
- * responding to UI state changes.
+ * State management in Redux apps work as follows:
+ *
+ *  1. All important application state is stored in a single, immutable object.
+ *  2. The user interface is a presentation of this state. Interaction with the
+ *     UI triggers updates by creating `actions`.
+ *  3. Actions are plain JS objects which describe some event that happened in
+ *     the application. Updates happen by passing actions to a `reducer`
+ *     function which takes the current application state, the action and
+ *     returns the new application state.
+ *
+ *     The process of updating the app state using an action is known as
+ *     'dispatching' the action.
+ *  4. Other parts of the app can subscribe to changes in the app state.
+ *     This is used to to update the UI etc.
+ *
+ * "middleware" functions can wrap the dispatch process in order to implement
+ *  logging, trigger side effects etc.
+ *
+ * Tests for a given action consist of:
+ *
+ *  1. Checking that the UI (or other event source) dispatches the correct
+ *     action when something happens.
+ *  2. Checking that given an initial state, and an action, a reducer returns
+ *     the correct resulting state.
+ *  3. Checking that the UI correctly presents a given state.
  */
 
 var redux = require('redux');
+
+// `.default` is needed because 'redux-thunk' is built as an ES2015 module
 var thunk = require('redux-thunk').default;
 
 var reducers = require('./reducers');
@@ -51,6 +76,9 @@ function angularDigestMiddleware($rootScope) {
 // @ngInject
 module.exports = function ($rootScope, settings) {
   var enhancer = redux.applyMiddleware(
+    // The `thunk` middleware handles actions which are functions.
+    // This is used to implement actions which have side effects or are
+    // asynchronous (see https://github.com/gaearon/redux-thunk#motivation)
     thunk,
     angularDigestMiddleware.bind(null, $rootScope)
   );

h/static/scripts/reducers/index.js

@@ -2,7 +2,8 @@
 
 /**
  * This module defines the main update function (or 'reducer' in Redux's
- * terminology) that handles app state updates.
+ * terminology) that handles app state updates. For an overview of how state
+ * management in Redux works, see the comments at the top of `annotation-ui.js`
  *
  * Each sub-module in this folder defines:
  *