Apply suggestions from code review

Co-authored-by: Vadim Dalecky <[email protected]>

src/plugins/data/public/search/README.md

@@ -1,23 +1,23 @@
 # search
 
-The `search` service provides you with APIs to query elasticsearch.
+The `search` service provides you with APIs to query Elasticsearch.
 
-The services are split into two parts:
+The services are split into two parts: (1) low-level API; and (2) high-level API.
 
-# low level API
+## Low-level API
 
 With low level API you work directly with elasticsearch DSL
 
 ```typescript
 const results = await data.search.search(request, params);
 ```
 
-# high level API
+## High-level API
 
-With high level API you work with kibana abstractions around elasticsearch DSL: filters, queries and aggregations.
+Using high-level API you work with Kibana abstractions around Elasticsearch DSL: filters, queries, and aggregations. Provided by the *Search Source* service.
 
 ```typescript
 const search = data.search.searchSource.createEmpty();
 search.setField('query', data.query.queryString);
 const results = await search.fetch();
-```
+```

src/plugins/data/public/search/search_source/search_source.ts

@@ -166,9 +166,10 @@ export class SearchSource {
   }
 
   /**
-   * internal, dont use
-   * overrides all fields with the new field array
-   * @param newFields
+   * Internal, do not use. Overrides all search source fields with the new field array.
+   *
+   * @private
+   * @param newFields New field array.
    */
   setFields(newFields: SearchSourceFields) {
     this.fields = newFields;
@@ -208,7 +209,7 @@ export class SearchSource {
   }
 
   /**
-   * deprecated, don't use
+   * @deprecated Don't use.
    */
   create() {
     return new SearchSource({}, this.dependencies);
@@ -296,7 +297,7 @@ export class SearchSource {
   }
 
   /**
-   * get resulting DSL
+   * Returns body contents of the search request, often referred as query DSL.
    */
   async getSearchRequestBody() {
     const searchRequest = await this.flatten();

src/plugins/data/public/types.ts

@@ -61,7 +61,7 @@ export interface DataPublicPluginSetup {
 }
 
 /**
- * data plugin prewired UI components
+ * Data plugin prewired UI components
  */
 export interface DataPublicPluginStartUi {
   IndexPatternSelect: React.ComponentType<IndexPatternSelectProps>;
@@ -111,7 +111,7 @@ export interface DataPublicPluginStart {
    */
   query: QueryStart;
   /**
-   * prewired ui components
+   * prewired UI components
    * {@link DataPublicPluginStartUi}
    */
   ui: DataPublicPluginStartUi;