Documentation for Client.js

web/app/static/js/modules/corpus_analysis/client/Client.js

@@ -4,7 +4,7 @@
  * It communicates with the server (e.g. connection or query)
  * and recieves data from it, if dynamicMode is true.
  * If dynamicMode is false, the client can also handle data that is already
- * loaded and is not coming in in chunks.
+ * loaded and is not coming in, in chunks.
  */
 class Client {
   constructor({corpusId = null,
@@ -19,12 +19,11 @@ class Client {
     this.eventListeners = {};
     this.connected = false;
 
-
     /**
-     * Disable all console logging.
+     * Disables all console logging.
      * This is global. So every other log message in every other Class or
      * function used in conjunction with the client either logs or does not
-     * log depending on the logging flag.
+     * log depending on the logging flag. It is kind of hacky but not bad.
      * Credits to https://gist.github.com/kmonsoor/0244fdb4ad79a4826371e58a1a5fa984
      */
     if (!logging) {
@@ -42,8 +41,11 @@ class Client {
     }
     console.info("Client initialized:", this);
   }
-
-  // Registers one or more SocketEventListeners to the Client.
+  /**
+   * Registers one or more event listeners to the Client. Either socket or
+   * custom javascript events. Event listeners are class instances of
+   * ClientEventListener implemented further below.
+   */
   setSocketEventListeners(eventListeners) {
     for (let eventListener of eventListeners) {
       this.eventListeners[eventListener.type] = eventListener;
@@ -51,8 +53,10 @@ class Client {
   }
 
   /**
-   * Loads the SocketEventListeners so they will be triggered on their assigned
-   * type strings because they double as the socket event event names.
+   * Loads the event listeners that have been registered with the function
+   * above so that they will be triggered on their assigned
+   * type strings. Type strings double as the socket event event names or
+   * javascript custom event names.
    */
   loadSocketEventListeners() {
     for (let [type, listener] of Object.entries(this.eventListeners)) {
@@ -61,8 +65,10 @@ class Client {
   }
 
   /**
-   * This functions sends events to the View to trigger specific functions that
-   * are handleing the representation of data stored in the model.
+   * This functions emits the 'notify-view' custom javascript event. This
+   * triggers specific functions in the View depending on the caseIdentifier.
+   * The detail object can hold any type of data the View needs to know about
+   * to represent those to the user.
    */
   notifyView(caseIdentifier, detailObject={}) {
     detailObject.caseIdentifier = caseIdentifier;
@@ -71,14 +77,9 @@ class Client {
     document.dispatchEvent(event);
   }
 
-  // Registers a CorpusAnalysisDisplay object to the Client.
-  setDisplay(type, corpusAnalysisDisplay) {
-    this.displays[type] = corpusAnalysisDisplay;
-  }
-
   /**
-   * Connects to the corpus analysis session for the specified corpus via
-   * socket.io.
+   * Connects to the corpus analysis session running on the server side for the
+   * specified corpus via socket.io.
    */
   connect() {
     console.info('corpus_analysis_init: Client connecting to session via',
@@ -86,6 +87,7 @@ class Client {
     this.socket.emit('corpus_analysis_init', this.corpusId);
   }
 
+  // Gets the meta data of the current corpus.
   getMetaData() {
     console.info('corpus_analysis_meta_data: Client getting meta data via',
                  'socket.emit.');
@@ -103,9 +105,9 @@ class Client {
   }
 
   /**
-   * Create results data either from all results or from all marked sub results
-   * Triggers emit to get full match context from server for a number of
-   * matches identified by their data_index.
+   * Requests results data either for, 'full-results', 'sub-results' or
+   * 'inspect-results' (resultsType).
+   * Gets full results for evere provided dataIndex (one match).
    **/
   getResultsData(resultsType, dataIndexes, results) {
     let tmp_first_cpos = [];
@@ -125,10 +127,12 @@ class Client {
 
 
 /**
- * This class is used to create an SocketEventListener.
+ * This class is used to create an event listener listening for socket or
+ * javascript custom events.
  * Input are an identifying type string, the listener function and callbacks
  * which will be executed as part of the listener function. The identifying
- * type string is also used as the socket event event identifier.
+ * type string is also used as the socket event or custom javascript event name
+ * identifier.
  */
 class ClientEventListener {
   constructor(type, listenerFunction) {
@@ -137,7 +141,7 @@ class ClientEventListener {
     this.type = type;
   }
 
-  // Registers callbacks to this SocketEventListener
+  // Registers callbacks to this ClientEventListener.
   setCallbacks(listenerCallbacks) {
     for (let listenerCallback of listenerCallbacks) {
       this.listenerCallbacks[listenerCallback.type] = listenerCallback;
@@ -159,7 +163,7 @@ class ClientEventListener {
                                         ...listenerCallback.args);
     }
   }
-  // use this if you only want to execute a specific registered callback
+  // Executes a specific registered callback by provoding a type string.
   executeCallback(defaultArgs, type) {
     let listenerCallback = this.listenerCallbacks[type];
     listenerCallback.callbackFunction(...defaultArgs,
@@ -169,7 +173,7 @@ class ClientEventListener {
 
 /**
  * This class is used to create an ListenerCallback which will be registered
- * to an SocketEventListener so the Listener can invoke the ListenerCallback
+ * to an ClientEventListener so the listener can invoke the associated
  * callback functions.
  */
 class ListenerCallback {
@@ -180,7 +184,7 @@ class ListenerCallback {
   }
 }
 
-// export Classes from this module
+// Export Classes from this module.
 export {
   Client,
   ClientEventListener,