docs: add missing inline docs for elasticsearch related interfaces

Closes #41

src/storage/elasticsearch/common.ts

@@ -17,10 +17,9 @@ import {SCThingType} from '@openstapps/core';
 import {SCThing} from '@openstapps/core';
 import {NameList} from 'elasticsearch';
 
-/* tslint:disable:completed-docs */ // TODO: document properties of interfaces
 /**
  * An elasticsearch bucket aggregation
- * @see https://www.elastic.co/guide/en/elasticsearch/reference/5.5/search-aggregations-bucket.html
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/5.6/search-aggregations-bucket.html
  */
 export interface AggregationSchema {
   [aggregationName: string]: ESTermsFilter;
@@ -33,11 +32,39 @@ export interface AggregationSchema {
  * explanation of what the parameters mean
  */
 export interface ElasticsearchQueryDisMaxConfig {
+  /**
+   * Relative (to a total number of documents) or absolute number to exclude meaningless matches that frequently appear
+   */
   cutoffFrequency: number;
+
+  /**
+   * The maximum allowed Levenshtein Edit Distance (or number of edits)
+   * @see https://www.elastic.co/guide/en/elasticsearch/reference/5.6/common-options.html#fuzziness
+   */
   fuzziness: number;
+
+  /**
+   * Increase the importance (relevance score) of a field
+   * @see https://www.elastic.co/guide/en/elasticsearch/reference/5.6/mapping-boost.html
+   */
   matchBoosting: number;
+
+  /**
+   * Minimal number (or percentage) of words that should match in a query
+   * @see https://www.elastic.co/guide/en/elasticsearch/reference/5.6/query-dsl-minimum-should-match.html
+   */
   minMatch: string;
+
+  /**
+   * Type of the query - in this case 'dis_max' which is a union of its subqueries
+   * @see https://www.elastic.co/guide/en/elasticsearch/reference/5.6/query-dsl-dis-max-query.html
+   */
   queryType: 'dis_max';
+
+  /**
+   * Changes behavior of default calculation of the score when multiple results match
+   * @see https://www.elastic.co/guide/en/elasticsearch/reference/5.6/query-dsl-multi-match-query.html#tie-breaker
+   */
   tieBreaker: number;
 }
 
@@ -48,26 +75,83 @@ export interface ElasticsearchQueryDisMaxConfig {
  * explanation of what the parameters mean
  */
 export interface ElasticsearchQueryQueryStringConfig {
+  /**
+   * Minimal number (or percentage) of words that should match in a query
+   * @see https://www.elastic.co/guide/en/elasticsearch/reference/5.6/query-dsl-minimum-should-match.html
+   */
   minMatch: string;
+
+  /**
+   * Type of the query - in this case 'query_string' which uses a query parser in order to parse content
+   * @see https://www.elastic.co/guide/en/elasticsearch/reference/5.6/query-dsl-query-string-query.html
+   */
   queryType: 'query_string';
 }
 
 /**
  * A hit in an elastiscsearch search result
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/5.6/mapping-fields.html
  */
 export interface ElasticsearchObject<T extends SCThing> {
+  /**
+   * Unique identifier of a document (object)
+   */
   _id: string;
+
+  /**
+   * The index to which the document belongs
+   */
   _index: string;
+
+  /**
+   * Relevancy of the document to a query
+   */
   _score: number;
+
+  /**
+   * The original JSON representing the body of the document
+   */
   _source: T;
+
+  /**
+   * The document's mapping type
+   * @see https://www.elastic.co/guide/en/elasticsearch/reference/5.6/mapping-type-field.html
+   */
   _type: string;
+
+  /**
+   * Version of the document
+   */
   _version?: number;
+
+  /**
+   * Used to index the same field in different ways for different purposes
+   * @see https://www.elastic.co/guide/en/elasticsearch/reference/5.6/multi-fields.html
+   */
   fields?: NameList;
-  // tslint:disable: no-any
+
+  /**
+   * Used to highlight search results on one or more fields
+   * @see https://www.elastic.co/guide/en/elasticsearch/reference/5.6/search-request-highlighting.html
+   */
+  // tslint:disable-next-line: no-any
   highlight?: any;
+
+  /**
+   * Used in when nested/children documents match the query
+   * @see https://www.elastic.co/guide/en/elasticsearch/reference/5.6/search-request-inner-hits.html
+   */
+  // tslint:disable-next-line: no-any
   inner_hits?: any;
-  // tslint:enable: no-any
+
+  /**
+   * Queries that matched for documents in results
+   */
   matched_queries?: string[];
+
+  /**
+   * Sorting definition
+   */
   sort?: string[];
 }
 
@@ -77,7 +161,13 @@ export interface ElasticsearchObject<T extends SCThing> {
  * The config file extends the SCConfig file by further defining how the database property
  */
 export interface ElasticsearchConfigFile {
+  /**
+   * Configuration that is not visible to clients
+   */
   internal: {
+    /**
+     * Database configuration
+     */
     database: ElasticsearchConfig;
   };
 }
@@ -86,8 +176,19 @@ export interface ElasticsearchConfigFile {
  * An elasticsearch configuration
  */
 export interface ElasticsearchConfig {
+  /**
+   * Name of the database
+   */
   name: 'elasticsearch';
+
+  /**
+   * Configuration for using queries
+   */
   query?: ElasticsearchQueryDisMaxConfig | ElasticsearchQueryQueryStringConfig;
+
+  /**
+   * Version of the used elasticsearch
+   */
   version: string;
 }
 
@@ -95,6 +196,9 @@ export interface ElasticsearchConfig {
  * An elasticsearch term filter
  */
 export interface ESTermFilter {
+  /**
+   * Definition of a term to match
+   */
   term: {
     [fieldName: string]: string;
   };
@@ -104,8 +208,18 @@ export interface ESTermFilter {
  * An elasticsearch terms filter
  */
 export interface ESTermsFilter {
+  /**
+   * Terms filter definition
+   */
   terms: {
+    /**
+     * Field to apply filter to
+     */
     field: string;
+
+    /**
+     * Number of results
+     */
     size?: number;
   };
 }
@@ -114,7 +228,13 @@ export interface ESTermsFilter {
  * An elasticsearch type filter
  */
 export interface ESTypeFilter {
+  /**
+   * Type filter definition
+   */
   type: {
+    /**
+     * Type name (SCThingType) to filter with
+     */
     value: SCThingType;
   };
 }
@@ -123,9 +243,19 @@ export interface ESTypeFilter {
  * Filter arguments for an elasticsearch geo distance filter
  */
 export interface ESGeoDistanceFilterArguments {
+  /**
+   * The radius of the circle centred on the specified location
+   */
   distance: string;
   [fieldName: string]: {
+    /**
+     * Latitute
+     */
     lat: number;
+
+    /**
+     * Longitude
+     */
     lon: number;
   } | string;
 }
@@ -134,16 +264,36 @@ export interface ESGeoDistanceFilterArguments {
  * An elasticsearch geo distance filter
  */
 export interface ESGeoDistanceFilter {
+  /**
+   * @see ESGeoDistanceFilterArguments
+   */
   geo_distance: ESGeoDistanceFilterArguments;
 }
 
 /**
  * Filter arguments for an elasticsearch boolean filter
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/5.6/query-dsl-bool-query.html
  */
 export interface ESBooleanFilterArguments<T> {
+  /**
+   * Minimal number (or percentage) of words that should match in a query
+   * @see https://www.elastic.co/guide/en/elasticsearch/reference/5.6/query-dsl-minimum-should-match.html
+   */
   minimum_should_match?: number;
+
+  /**
+   * The clause (query) must appear in matching documents and will contribute to the score.
+   */
   must?: T[];
+
+  /**
+   * The clause (query) must not appear in the matching documents.
+   */
   must_not?: T[];
+
+  /**
+   * The clause (query) should appear in the matching document.
+   */
   should?: T[];
 }
 
@@ -151,16 +301,35 @@ export interface ESBooleanFilterArguments<T> {
  * An elasticsearch boolean filter
  */
 export interface ESBooleanFilter<T> {
+ /**
+  * @see ESBooleanFilterArguments
+  */
   bool: ESBooleanFilterArguments<T>;
 }
 
 /**
  * An elasticsearch function score query
+ * @see https://www.elastic.co/guide/en/elasticsearch/reference/5.6/query-dsl-function-score-query.html
  */
 export interface ESFunctionScoreQuery {
+  /**
+   * Function score definition
+   */
   function_score: {
+    /**
+     * Functions that compute score for query results (documents)
+     * @see ESFunctionScoreQueryFunction
+     */
     functions: ESFunctionScoreQueryFunction[];
+
+    /**
+     * @see ESBooleanFilter
+     */
     query: ESBooleanFilter<unknown>;
+
+    /**
+     * Specifies how the computed scores are combined
+     */
     score_mode: 'multiply';
   };
 }
@@ -169,7 +338,14 @@ export interface ESFunctionScoreQuery {
  * An function for an elasticsearch functions score query
  */
 export interface ESFunctionScoreQueryFunction {
+  /**
+   * Function is applied only if a document matches the given filtering query
+   */
   filter: ESTermFilter | ESTypeFilter | ESBooleanFilter<ESTermFilter | ESTypeFilter>;
+
+  /**
+   * Weight (importance) of the filter
+   */
   weight: number;
 }
 
@@ -184,11 +360,29 @@ export interface ESDucetSort {
  * Sort arguments for an elasticsearch geo distance sort
  */
 export interface ESGeoDistanceSortArguments {
+  /**
+   * What value to pick for sorting
+   */
   mode: 'avg' | 'max' | 'median' | 'min';
+
+  /**
+   * Order
+   */
   order: 'asc' | 'desc';
+
+  /**
+   * Value unit
+   */
   unit: 'm';
   [field: string]: {
+    /**
+     * Latitute
+     */
     lat: number;
+
+    /**
+     * Longitude
+     */
     lon: number;
   } | string;
 }
@@ -197,6 +391,9 @@ export interface ESGeoDistanceSortArguments {
  * An elasticsearch geo distance sort
  */
 export interface ESGeoDistanceSort {
+  /**
+   * @see ESGeoDistanceFilterArguments
+   */
   _geo_distance: ESGeoDistanceSortArguments;
 }
 
@@ -204,9 +401,23 @@ export interface ESGeoDistanceSort {
  * An elasticsearch script sort
  */
 export interface ScriptSort {
+   /**
+    * A script
+    */
   _script: {
+    /**
+     * Order
+     */
     order: 'asc' | 'desc';
+
+    /**
+     * The custom script used for sorting
+     */
     script: string;
+
+    /**
+     * What type is being sorted
+     */
     type: 'number' | 'string';
   };
 }