Comment the frontend SemanticQuery model and tests (#486)

frontend/src/semantic-search/model-test.ts

@@ -18,6 +18,10 @@ describe('semantic search model', function() {
         this.model = new SemanticQuery({
             id: '1',
             label: 'test 123',
+            // A hand-written example of what the IR of a very simple query
+            // looks like. This is intended to have a complete set of models and
+            // attributes as they would be encountered in a real scenario,
+            // though not all values are entirely accurate.
             query: new Model({
                 chain: new Collection([{
                     range: this.ontology,
@@ -62,6 +66,7 @@ describe('semantic search model', function() {
         this.minimalJSON = {
             id: '1',
             label: 'test 123',
+            // Leaner backend serialization of the same query as above.
             query: {
                 chain: [{
                     range: idOnlyOntology,

frontend/src/semantic-search/model.ts

@@ -16,6 +16,10 @@ import Graph from '../common-rdf/graph';
 
 import { logic, filters } from './dropdown-constants';
 
+// Core recursive implementation of SemanticQuery.toJSON. Traverse recursive
+// datastructure `json` and return a copy in which all models and collections
+// are replaced by their plain JSON representations and models with an id are
+// reduced to a plain object with only the id attribute.
 function pruneResources(json: any): any {
     if (!isObject(json)) return json;
     if (isFunction(json['toJSON'])) return pruneResources(json['toJSON']());
@@ -25,6 +29,9 @@ function pruneResources(json: any): any {
     return mapValues(json, pruneResources);
 }
 
+// Core recursive implementation of SemanticQuery.parse, the inverse of
+// pruneResources. Since pruneResources is lossy, full recovery is only possible
+// because we have domain-specific knowledge of our internal data model.
 function parseQuery(json: any, key?: string | number): any {
     if (!isObject(json)) return json;
     if (isArray(json)) {
@@ -39,6 +46,15 @@ function parseQuery(json: any, key?: string | number): any {
     return new Model(mapValues(json, parseQuery));
 }
 
+/**
+ * SemanticQuery is our frontend representation of the semantic query as it is
+ * saved at the backend. Its `query` attribute contains the rich intermediate
+ * representation (IR) as described in the README. The `toJSON` and `parse`
+ * methods take care of converting the IR respectively to and from the leaner
+ * JSON representation that is exchanged with the backend. These methods are
+ * called automatically when we use the built-in `save` and `fetch` methods, so
+ * we don't need to invoke them explicitly.
+ */
 export default class SemanticQuery extends Model {
     toJSON(options?: any): any {
         const json = super.toJSON(options);