Rename xorSelectedAnnotations -> toggleSelectedAnnotations

Give this method a more obvious name and improve a couple of other
documentation comments.

h/static/scripts/annotation-ui-sync.js

@@ -36,7 +36,7 @@ function AnnotationUISync($rootScope, $window, bridge, annotationSync,
     toggleAnnotationSelection: function (tags) {
       tags = tags || [];
       var annotations = getAnnotationsByTags(tags);
-      annotationUI.xorSelectedAnnotations(annotations);
+      annotationUI.toggleSelectedAnnotations(annotations);
     },
     setVisibleHighlights: function (state) {
       if (typeof state !== 'boolean') {

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/).
+ *
+ * Redux is used to provide a predictable way of updating UI state and
+ * responding to UI state changes.
+ */
+
 var immutable = require('seamless-immutable');
 var redux = require('redux');
 
-function value(selection) {
+function freeze(selection) {
   if (Object.keys(selection).length) {
     return immutable(selection);
   } else {
@@ -16,7 +24,7 @@ function initialSelection(settings) {
   if (settings.annotations) {
     selection[settings.annotations] = true;
   }
-  return value(selection);
+  return freeze(selection);
 }
 
 function initialState(settings) {
@@ -65,7 +73,7 @@ module.exports = function (settings) {
   function select(annotations) {
     store.dispatch({
       type: types.SELECT_ANNOTATIONS,
-      selection: value(annotations),
+      selection: freeze(annotations),
     });
   }
 
@@ -103,7 +111,7 @@ module.exports = function (settings) {
       }
       store.dispatch({
         type: types.FOCUS_ANNOTATIONS,
-        focused: value(selection),
+        focused: freeze(selection),
       });
     },
 
@@ -140,7 +148,7 @@ module.exports = function (settings) {
     },
 
     /** Toggle whether annotations are selected or not. */
-    xorSelectedAnnotations: function (annotations) {
+    toggleSelectedAnnotations: function (annotations) {
       var selection = Object.assign({}, store.getState().selectedAnnotationMap);
       for (var i = 0, annotation; i < annotations.length; i++) {
         annotation = annotations[i];

h/static/scripts/test/annotation-ui-test.js

@@ -116,10 +116,10 @@ describe('annotationUI', function () {
     });
   });
 
-  describe('#xorSelectedAnnotations()', function () {
+  describe('#toggleSelectedAnnotations()', function () {
     it('adds annotations missing from the selectedAnnotationMap', function () {
       annotationUI.selectAnnotations([{ id: 1 }, { id: 2}]);
-      annotationUI.xorSelectedAnnotations([{ id: 3 }, { id: 4 }]);
+      annotationUI.toggleSelectedAnnotations([{ id: 3 }, { id: 4 }]);
       assert.deepEqual(annotationUI.getState().selectedAnnotationMap, {
         1: true, 2: true, 3: true, 4: true
       });
@@ -127,13 +127,13 @@ describe('annotationUI', function () {
 
     it('removes annotations already in the selectedAnnotationMap', function () {
       annotationUI.selectAnnotations([{id: 1}, {id: 3}]);
-      annotationUI.xorSelectedAnnotations([{ id: 1 }, { id: 2 }]);
+      annotationUI.toggleSelectedAnnotations([{ id: 1 }, { id: 2 }]);
       assert.deepEqual(annotationUI.getState().selectedAnnotationMap, { 2: true, 3: true });
     });
 
     it('nulls the map if no annotations are selected', function () {
       annotationUI.selectAnnotations([{id: 1}]);
-      annotationUI.xorSelectedAnnotations([{ id: 1 }]);
+      annotationUI.toggleSelectedAnnotations([{ id: 1 }]);
       assert.isNull(annotationUI.getState().selectedAnnotationMap);
     });
   });