doc: Document reducers/eventLogging module

Bug: T158236
Change-Id: I327f11ba804063a912c355477e9247a99e9b6e32

src/reducers/eventLogging.js

@@ -1,10 +1,13 @@
+/**
+ * @module reducers/eventLogging
+ */
+
 var actionTypes = require( './../actionTypes' ),
 	nextState = require( './nextState' ),
 	counts = require( './../counts' );
 
 /**
- * Initialize the data that's shared between all
- * [Popups](https://meta.wikimedia.org/wiki/Schema:Popups) events.
+ * Initialize the data that's shared between all events.
  *
  * @param {Object} bootAction
  * @return {Object}
@@ -33,11 +36,12 @@ function getBaseData( bootAction ) {
  * Takes data specific to the action and adds the following properties:
  *
  * * `linkInteractionToken`;
- * * `pageTitleHover` and `namespaceIdHover`.
+ * * `pageTitleHover` and `namespaceIdHover`; and
+ * * `previewType` and `perceivedWait`, if a preview has been shown.
  *
  * @param {Object} interaction
  * @param {Object} actionData Data specific to the action, e.g. see
- *  `createClosingEvent`
+ *  {@link module:reducers/eventLogging~createClosingEvent `createClosingEvent`}
  * @return {Object}
  */
 function createEvent( interaction, actionData ) {
@@ -55,15 +59,15 @@ function createEvent( interaction, actionData ) {
 }
 
 /**
- * Creates an event that, when mixed into the base data (see `getBaseData`),
- * represents the user abandoning a link or preview.
+ * Creates an event that, when mixed into the base data (see
+ * {@link module:reducers/eventLogging~getBaseData `getBaseData`}), represents
+ * the user abandoning a link or preview.
  *
  * Since the event should be logged when the user has either abandoned a link or
  * dwelled on a different link, we refer to these events as "closing" events as
  * the link interaction has finished and a new one will be created later.
  *
- * If the link interaction is finalized, i.e. if an event has already been
- * logged for the link interaction, then no closing event is created.
+ * If the link interaction is finalized, then no closing event is created.
  *
  * @param {Object} interaction
  * @return {Object|undefined}
@@ -86,36 +90,30 @@ function createClosingEvent( interaction ) {
 }
 
 /**
- * Reducer for actions that may result in an event being logged with the
- * Popups schema via Event Logging.
+ * Reducer for actions that may result in an event being logged with [the
+ * Popups schema][0] via EventLogging.
  *
- * TODO: For obvious reasons, this reducer and the associated change listener
- * are tightly bound to the Popups schema. This reducer must be
- * renamed/moved if we introduce additional instrumentation.
- *
- * The complexity of this reducer reflects the complexity of the
- * [Popups](https://meta.wikimedia.org/wiki/Schema:Popups) instrumentation. This
- * complexity is further increased by requiring that actions are conditionally
- * reduced rather than conditionally dispatched in order to handle two delays
- * introduced by the system in order to provide a consistent UX.
+ * The complexity of this reducer reflects the complexity of [the schema][0],
+ * which is compounded by the introduction of two delays introduced by the
+ * system to provide reasonable performance and a consistent UX.
  *
  * The reducer must:
  *
- * * Accumulate the state required to log
- *   [Popups](https://meta.wikimedia.org/wiki/Schema:Popups) events. This state
- *   is referred to as "the interaction state" or "the interaction";
- * * Handle only logging only one event per link interaction;
- * * Defend against delayed actions being dispatched and, as a direct
- *   consequence;
+ * * Accumulate the state required to log events. This state is
+ *   referred to as "the interaction state" or "the interaction";
+ * * Enforce the invariant that one event is logged per interaction;
+ * * Defend against delayed actions being dispatched; and, as a direct
+ *   consequence
  * * Handle transitioning from one interaction to another at the same time.
  *
  * Furthermore, we distinguish between "finalizing" and "closing" the current
- * interaction state. Since only one
- * [Popups](https://meta.wikimedia.org/wiki/Schema:Popups) event should be
- * logged per link interaction, we say that the interaction state is
- * //finalized// when an event has been logged and is //closed// when a new
- * interaction state should be created, e.g. the interaction state is only
- * finalized when the user clicks a link or a preview.
+ * interaction state. Since only one event should be logged per link
+ * interaction, we say that the interaction state is *finalized* when an event
+ * has been logged and is *closed* when a new interaction should be created.
+ * In practice, the interaction state is only finalized when the user clicks a
+ * link or a preview.
+ *
+ * [0]: https://meta.wikimedia.org/wiki/Schema:Popups
  *
  * @param {Object} state
  * @param {Object} action