add TypeDocs about the IndexReducer and its selectors

src/app/core/index/index.reducer.ts

@@ -6,16 +6,34 @@ import {
   RemoveFromIndexByValueAction
 } from './index.actions';
 
+/**
+ * An enum containing all index names
+ */
 export enum IndexName {
+  // Contains all objects in the object cache indexed by UUID
   OBJECT = 'object/uuid-to-self-link',
+
+  // contains all requests in the request cache indexed by UUID
   REQUEST = 'get-request/href-to-uuid',
+
+  /**
+   * Contains the UUIDs of requests that were sent to the server and
+   * have their responses cached, indexed by the UUIDs of requests that
+   * weren't sent because the response they requested was already cached
+   */
   UUID_MAPPING = 'get-request/configured-to-cache-uuid'
 }
 
+/**
+ * The state of a single index
+ */
 export interface IndexState {
   [key: string]: string
 }
 
+/**
+ * The state that contains all indices
+ */
 export type MetaIndexState = {
   [name in IndexName]: IndexState
 }
@@ -23,6 +41,16 @@ export type MetaIndexState = {
 // Object.create(null) ensures the object has no default js properties (e.g. `__proto__`)
 const initialState: MetaIndexState = Object.create(null);
 
+/**
+ * The Index Reducer
+ *
+ * @param state
+ *    the current state
+ * @param action
+ *    the action to perform on the state
+ * @return MetaIndexState
+ *    the new state
+ */
 export function indexReducer(state = initialState, action: IndexAction): MetaIndexState {
   switch (action.type) {
 
@@ -44,6 +72,16 @@ export function indexReducer(state = initialState, action: IndexAction): MetaInd
   }
 }
 
+/**
+ * Add an entry to a given index
+ *
+ * @param state
+ *    The MetaIndexState that contains all indices
+ * @param action
+ *    The AddToIndexAction containing the value to add, and the index to add it to
+ * @return MetaIndexState
+ *    the new state
+ */
 function addToIndex(state: MetaIndexState, action: AddToIndexAction): MetaIndexState {
   const subState = state[action.payload.name];
   const newSubState = Object.assign({}, subState, {
@@ -55,6 +93,16 @@ function addToIndex(state: MetaIndexState, action: AddToIndexAction): MetaIndexS
   return obs;
 }
 
+/**
+ * Remove a entries that contain a given value from a given index
+ *
+ * @param state
+ *    The MetaIndexState that contains all indices
+ * @param action
+ *    The RemoveFromIndexByValueAction containing the value to remove, and the index to remove it from
+ * @return MetaIndexState
+ *    the new state
+ */
 function removeFromIndexByValue(state: MetaIndexState, action: RemoveFromIndexByValueAction): MetaIndexState {
   const subState = state[action.payload.name];
   const newSubState = Object.create(null);
@@ -69,9 +117,14 @@ function removeFromIndexByValue(state: MetaIndexState, action: RemoveFromIndexBy
 }
 
 /**
- * Remove values from the IndexState's substate that contain a given substring
- * @param state     The IndexState to remove values from
- * @param action    The RemoveFromIndexByValueAction containing the necessary information to remove the values
+ * Remove entries that contain a given substring from a given index
+ *
+ * @param state
+ *    The MetaIndexState that contains all indices
+ * @param action
+ *    The RemoveFromIndexByValueAction the substring to remove, and the index to remove it from
+ * @return MetaIndexState
+ *    the new state
  */
 function removeFromIndexBySubstring(state: MetaIndexState, action: RemoveFromIndexByValueAction): MetaIndexState {
   const subState = state[action.payload.name];

src/app/core/index/index.selectors.ts

@@ -5,38 +5,87 @@ import { CoreState } from '../core.reducers';
 import { coreSelector } from '../core.selectors';
 import { IndexName, IndexState, MetaIndexState } from './index.reducer';
 
+/**
+ * Return the MetaIndexState based on the CoreSate
+ *
+ * @returns
+ *    a MemoizedSelector to select the MetaIndexState
+ */
 export const metaIndexSelector: MemoizedSelector<AppState, MetaIndexState> = createSelector(
   coreSelector,
   (state: CoreState) => state.index
 );
+
+/**
+ * Return the object index based on the MetaIndexState
+ * It contains all objects in the object cache indexed by UUID
+ *
+ * @returns
+ *    a MemoizedSelector to select the object index
+ */
 export const objectIndexSelector: MemoizedSelector<AppState, IndexState> = createSelector(
   metaIndexSelector,
   (state: MetaIndexState) => state[IndexName.OBJECT]
 );
+
+/**
+ * Return the request index based on the MetaIndexState
+ *
+ * @returns
+ *    a MemoizedSelector to select the request index
+ */
 export const requestIndexSelector: MemoizedSelector<AppState, IndexState> = createSelector(
   metaIndexSelector,
   (state: MetaIndexState) => state[IndexName.REQUEST]
 );
+
+/**
+ * Return the request UUID mapping index based on the MetaIndexState
+ *
+ * @returns
+ *    a MemoizedSelector to select the request UUID mapping
+ */
 export const requestUUIDIndexSelector: MemoizedSelector<AppState, IndexState> = createSelector(
   metaIndexSelector,
   (state: MetaIndexState) => state[IndexName.UUID_MAPPING]
 );
+
+/**
+ * Return the self link of an object in the object-cache based on its UUID
+ *
+ * @param uuid
+ *    the UUID for which you want to find the matching self link
+ * @returns
+ *    a MemoizedSelector to select the self link
+ */
 export const selfLinkFromUuidSelector =
   (uuid: string): MemoizedSelector<AppState, string> => createSelector(
     objectIndexSelector,
     (state: IndexState) => hasValue(state) ? state[uuid] : undefined
   );
+
+/**
+ * Return the UUID of a GET request based on its href
+ *
+ * @param href
+ *    the href of the GET request
+ * @returns
+ *    a MemoizedSelector to select the UUID
+ */
 export const uuidFromHrefSelector =
   (href: string): MemoizedSelector<AppState, string> => createSelector(
     requestIndexSelector,
     (state: IndexState) => hasValue(state) ? state[href] : undefined
   );
+
 /**
- * If a request wasn't sent to the server because the result was already cached,
- * this selector allows you to find the UUID of the cached request based on the
- * UUID of the new request
+ * Return the UUID of a cached request based on the UUID of a request
+ * that wasn't sent because the response was already cached
  *
- * @param uuid    The uuid of the new request
+ * @param uuid
+ *    The UUID of the new request
+ * @returns
+ *    a MemoizedSelector to select the UUID of the cached request
  */
 export const originalRequestUUIDFromRequestUUIDSelector =
   (uuid: string): MemoizedSelector<AppState, string> => createSelector(