Cleanup

Author: JasonStoltz

src/app-search/AppSearchDriver.js

@@ -41,20 +41,31 @@ const DEFAULT_STATE = {
  * The Driver is a framework agnostic state manager for App Search apps. Meaning,
  * it is the source of truth for state in this React App, but it has no
  * dependencies on React itself.
+ *
+ * The public interface of the Driver can be thought about in the following
+ * way:
+ *
+ * Ways to GET state:
+ * - getState - Get the initial app state
+ * - subscribeToStateChanges - Get updated state whenever it changes
+ *
+ * Ways to SET state, or "Actions" as we refer to them elsewhere
+ * - addFilter, etc, will typically update the state and trigger new queries
+ *
  */
 export default class AppSearchDriver {
  state = DEFAULT_STATE;
 
  /**
  *
- * @param options {*}
- *
+ * @param options Object
  * engineName - Engine to query, found in your App Search Dashboard
  * hostIdentifier - Credential found in your App Search Dashboard
- * initialState - This lets you set initial search parameters
+ * initialState - This lets you set initial search parameters, ex:
+ * `searchTerm: "test"`
  * searchKey - Credential found in your App Search Dashboard
- * searchOptions - A low level configuration which let's you configure
- * the options used on the Search API endpoint
+ * searchOptions - A low level configuration which lets you configure
+ *  the options used on the Search API endpoint, ex: `result_fields`
  */
  constructor({
  engineName,
@@ -76,10 +87,11 @@ export default class AppSearchDriver {
  this.URLManager.onURLStateChange(urlState => {
  this._updateSearchResults({ ...DEFAULT_STATE, ...urlState }, true);
  });
- // We filter these here, because the only state that should be allowed
- // to be passed in, is search parameter state. Results, etc, should not
- // be allowed to be passed in, that should be generated based on the
- // provided search parameters.
+
+ // We filter these here to disallow anything other than valid search
+ // parameters to be passed in initial state, or url state. `results`, etc,
+ // should not be allowed to be passed in, that should be generated based on
+ // the results of the query
  const searchParameters = filterSearchParameters({
  ...this.state,
  ...initialState,
@@ -88,15 +100,15 @@ export default class AppSearchDriver {
 
  // Initialize the state without calling _setState, because we don't
  // want to trigger an update callback, we're just initializing the state
- // to the correct default values.
+ // to the correct default values for the initial UI render
  this.state = {
  ...this.state,
  ...searchParameters
  };
 
- // We'll trigger an initial search if initial parameters contains
+ // We'll trigger an initial search if initial parameters contain
  // a search term or filters, otherwise, we'll just save their selections
- // in state as defaults.
+ // in state as initial values.
  if (searchParameters.searchTerm || searchParameters.filters.length > 0) {
  this._updateSearchResults(searchParameters);
  }
@@ -310,6 +322,13 @@ export default class AppSearchDriver {
  });
  };
 
+ /**
+ * Set the current page
+ *
+ * Will trigger new search
+ *
+ * @param current Integer
+ */
  setCurrent = current => {
  const {
  filters,

src/app-search/AppSearchProvider.js

@@ -5,10 +5,16 @@ import AppSearchContext from "./AppSearchContext";
 
 /**
  * The AppSearchProvider is the glue that connects the AppSearchDriver to
- * our React App. It "subscribes" to the driver in order to be
- * notified of state updates, and then passes that state down to child
- * components in a React Context. It will also pass down "actions" from the
- * AppSearchDriver, which allow child components to update state.
+ * our React App.
+ *
+ * It "subscribes" to the AppSearchDriver in order to be notified of state
+ * changes. It then syncs that state with its own state and passes that state
+ * down to child components in a React Context. It will also pass down "Actions"
+ * from the AppSearchDriver, which allow child components to update state.
+ *
+ * Any "Container" component placed within this context will have access
+ * to the Driver's state and Actions.
+ *
  */
 class AppSearchProvider extends Component {
  static propTypes = {
@@ -45,7 +51,7 @@ class AppSearchProvider extends Component {
  searchTerm,
  sortDirection,
  sortField,
- // Result data
+ // Result State
  facets,
  requestId,
  results,

src/app-search/withAppSearch.js

@@ -2,6 +2,11 @@ import React from "react";
 
 import AppSearchConsumer from "../app-search/AppSearchConsumer";
 
+/**
+ * This is a Higher Order Component that is used to expose (as `props`) all
+ * state and Actions provided by the AppSearchProvider to "container"
+ * components.
+ */
 export default function withAppSearch(Component) {
  return function(props) {
  return (

src/config/config-helper.js

@@ -4,10 +4,10 @@ import { create } from "../types/SortOption";
 /**
  * This file abstracts most logic around the configuration of the Reference UI.
  *
- * Configuration is an important part of the "reusability" and "genericness" of the
- * Reference UI, but if you are using this app as a starting point for own
- * project, everything related to configuration can largely be thrown away. To that
- * end, this file attempts to contain most of that logic to one place.
+ * Configuration is an important part of the "reusability" and "generic-ness" of
+ * the Reference UI, but if you are using this app as a starting point for own
+ * project, everything related to configuration can largely be thrown away. To
+ * that end, this file attempts to contain most of that logic to one place.
  */
 
 export function getConfig() {