[ADF-3806] Updated Search Service docs (#4044)

docs/core/search.service.md

@@ -2,6 +2,7 @@
 Title: Search service
 Added: v2.0.0
 Status: Active
+Last reviewed: 2018-12-03
 ---
 
 # [Search service](../../lib/core/services/search.service.ts "Defined in search.service.ts")
@@ -13,25 +14,31 @@ Accesses the Content Services Search API.
 ### Methods
 
 -   **getNodeQueryResults**(term: `string`, options?: [`SearchOptions`](../../lib/core/services/search.service.ts)): [`Observable`](http://reactivex.io/documentation/observable.html)`<`[`NodePaging`](../../lib/content-services/document-list/models/document-library.model.ts)`>`<br/>
-
+    Gets a list of nodes that match the given search criteria.
-    -   _term:_ `string`  - 
+    -   _term:_ `string`  - Term to search for
-    -   _options:_ [`SearchOptions`](../../lib/core/services/search.service.ts)  - (Optional) (Optional) 
+    -   _options:_ [`SearchOptions`](../../lib/core/services/search.service.ts)  - (Optional) Options for delivery of the search results
-    -   **Returns** [`Observable`](http://reactivex.io/documentation/observable.html)`<`[`NodePaging`](../../lib/content-services/document-list/models/document-library.model.ts)`>` - 
+    -   **Returns** [`Observable`](http://reactivex.io/documentation/observable.html)`<`[`NodePaging`](../../lib/content-services/document-list/models/document-library.model.ts)`>` - List of nodes resulting from the search
-
 -   **search**(searchTerm: `string`, maxResults: `number`, skipCount: `number`): [`Observable`](http://reactivex.io/documentation/observable.html)`<`[`NodePaging`](../../lib/content-services/document-list/models/document-library.model.ts)`>`<br/>
-
+    Performs a search.
-    -   _searchTerm:_ `string`  - 
+    -   _searchTerm:_ `string`  - Term to search for
-    -   _maxResults:_ `number`  - 
+    -   _maxResults:_ `number`  - Maximum number of items in the list of results
-    -   _skipCount:_ `number`  - 
+    -   _skipCount:_ `number`  - Number of higher-ranked items to skip over in the list
-    -   **Returns** [`Observable`](http://reactivex.io/documentation/observable.html)`<`[`NodePaging`](../../lib/content-services/document-list/models/document-library.model.ts)`>` - 
+    -   **Returns** [`Observable`](http://reactivex.io/documentation/observable.html)`<`[`NodePaging`](../../lib/content-services/document-list/models/document-library.model.ts)`>` - List of search results
-
 -   **searchByQueryBody**(queryBody: `QueryBody`): [`Observable`](http://reactivex.io/documentation/observable.html)`<`[`NodePaging`](../../lib/content-services/document-list/models/document-library.model.ts)`>`<br/>
-
+    Performs a search with its parameters supplied by a QueryBody object.
-    -   _queryBody:_ `QueryBody`  - 
+    -   _queryBody:_ `QueryBody`  - Object containing the search parameters
-    -   **Returns** [`Observable`](http://reactivex.io/documentation/observable.html)`<`[`NodePaging`](../../lib/content-services/document-list/models/document-library.model.ts)`>` -
+    -   **Returns** [`Observable`](http://reactivex.io/documentation/observable.html)`<`[`NodePaging`](../../lib/content-services/document-list/models/document-library.model.ts)`>` - List of search results
 
 ## Details
 
 See the
-[Alfresco JS API](https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-search-rest-api/docs/SearchApi.md#search)
+[search method](https://github.com/Alfresco/alfresco-js-api/blob/master/src/alfresco-search-rest-api/docs/SearchApi.md#search)
-for the format of the query and returned data.
+in the Alfresco JS-API for the format of the query and returned data.
+The [Search Configuration service](../core/search-configuration.service.md) 
+has a method to generate the QueryBody object used by `searchByQueryBody`. The properties of the
+SearchOptions
+interface are documented in source file comments.
+
+## See also
+
+-   [Search Configuration service](../core/search-configuration.service.md)

lib/core/services/search.service.ts

@@ -33,6 +33,12 @@ export class SearchService {
                 private searchConfigurationService: SearchConfigurationService) {
     }
 
+    /**
+     * Gets a list of nodes that match the given search criteria.
+     * @param term Term to search for
+     * @param options Options for delivery of the search results
+     * @returns List of nodes resulting from the search
+     */
     getNodeQueryResults(term: string, options?: SearchOptions): Observable<NodePaging> {
         const promise = this.apiService.getInstance().core.queriesApi.findNodes(term, options);
 
@@ -45,6 +51,13 @@ export class SearchService {
         );
     }
 
+    /**
+     * Performs a search.
+     * @param searchTerm Term to search for
+     * @param maxResults Maximum number of items in the list of results
+     * @param skipCount Number of higher-ranked items to skip over in the list
+     * @returns List of search results
+     */
     search(searchTerm: string, maxResults: number, skipCount: number): Observable<NodePaging> {
         const searchQuery = Object.assign(this.searchConfigurationService.generateQueryBody(searchTerm, maxResults, skipCount));
         const promise = this.apiService.getInstance().search.searchApi.search(searchQuery);
@@ -58,6 +71,11 @@ export class SearchService {
         );
     }
 
+    /**
+     * Performs a search with its parameters supplied by a QueryBody object.
+     * @param queryBody Object containing the search parameters
+     * @returns List of search results
+     */
     searchByQueryBody(queryBody: QueryBody): Observable<NodePaging> {
         const promise = this.apiService.getInstance().search.searchApi.search(queryBody);
 
@@ -76,11 +94,39 @@ export class SearchService {
 }
 
 export interface SearchOptions {
+    /** The number of entities that exist in the collection before those included in this list. */
     skipCount?: number;
+
+    /** The maximum number of items to return in the list. */
     maxItems?: number;
+
+    /** The id of the node to start the search from. Supports the aliases -my-, -root- and -shared-. */
     rootNodeId?: string;
+
+    /** Restrict the returned results to only those of the given node type and its sub-types. */
     nodeType?: string;
+
+    /**
+     * Return additional information about the node. The available optional fields are:
+     * `allowableOperations`, `aspectNames`, `isLink`, `isLocked`, `path` and `properties`.
+     */
     include?: string[];
+
+    /**
+     * String to control the order of the entities returned in a list. You can use this
+     * parameter to sort the list by one or more fields. Each field has a default sort order,
+     * which is normally ascending order (but see the JS-API docs to check if any fields used
+     * in a method have a descending default search order). To sort the entities in a specific
+     * order, you can use the "ASC" and "DESC" keywords for any field.
+     */
     orderBy?: string;
+
+    /**
+     * List of field names. You can use this parameter to restrict the fields returned within
+     * a response if, for example, you want to save on overall bandwidth. The list applies to a
+     * returned individual entity or entries within a collection. If the API method also supports
+     * the `include` parameter, then the fields specified in the include parameter are returned in
+     * addition to those specified in the fields parameter.
+     */
     fields?: string[];
 }