DOC-1283 - Revise content of Class QueryStateModel (#591)

* DOC-1283 - Revise content of Class QueryStateModel

- Also revised the `Coveo.state` documentation.

* Made required documentation adjustments.
https://coveord.atlassian.net/browse/DOC-1283

src/models/QueryStateModel.ts

@@ -27,16 +27,35 @@ export interface IQueryStateExcludedAttribute {
 }
 
 /**
- * The QueryStateModel is a key->value store of the state of every component that can affect a query.<br/>
- * Component set values in this key -> value store, and listen to event triggered to react accordingly.<br/>
- * For example, when a query is launched, the searchbox will set the 'q' attribute, the pager will set the 'first' attribute, etc.<br/>
- * At the same time, this class will trigger the associated event when a value is modified.<br/>
- * eg : The user change the content of the searchbox, and submit a query. This will trigger the following events :<br/>
- * -- state:change:q (because the value of 'q' changed)</br>
- * -- state:change (because at least one value changed in the query state)<br/>
- * Component or external code could hook handler on those events : document.addEventListener('state:change:q', handler);<br/>
- * See : {@link Model}, as all the relevant method are exposed in the base class.<br/>
- * Optionally, the state can be persisted to the query string to allow browser history management : See {@link HistoryController}
+ * The `QueryStateModel` class is a key-value store which contains the current state of the components that can affect
+ * the query (see [State](https://developers.coveo.com/x/RYGfAQ)). This class inherits from the [`Model`]{@link Model}
+ * class. Optionally, it is possible to persist the state in the query string in order to enable browser history
+ * management (see the [`HistoryController`]{@link HistoryController} class).
+ *
+ * Components set values in the `QueryStateModel` instance to reflect their current state. The `QueryStateModel`
+ * triggers state events (see [`eventTypes`]{@link Model.eventTypes}) whenever one of its values is modified. Components
+ * listen to triggered state events to update themselves when appropriate.
+ *
+ * For instance, when a query is triggered, the [`Searchbox`]{@link Searchbox} component sets the `q` attribute (the
+ * basic query expression), while the [`Pager`]{@link Pager} component sets the `first` attribute (the index of the
+ * first result to display in the result list), and so on.
+ *
+ * **Example:**
+ *
+ * > The user modifies the content of the `Searchbox` and submits a query. This triggers the following state events:
+ * > - `state:change:q` (because the value of `q` has changed).
+ * > - `state:change` (because at least one value has changed in the `QueryStateModel`).
+ * >
+ * > Components or external code can attach handlers to those events:
+ * > ```javascript
+ * > Coveo.$$(document).on('state:change:q', function() {
+ * >   [ ... ]
+ * > });
+ * > ```
+ *
+ * **Note:**
+ * > Normally, you should interact with the `QueryStateModel` instance using the [`Coveo.state`]{@link state} top-level
+ * > function.
  */
 export class QueryStateModel extends Model {
   static ID = 'state';
@@ -78,19 +97,19 @@ export class QueryStateModel extends Model {
   }
 
   /**
-   * Create a new QueryState
-   * @param element
-   * @param attributes
-   * @param bindings
+   * Creates a new `QueryStateModel` instance.
+   * @param element The HTMLElement on which to instantiate the `QueryStateModel`.
+   * @param attributes The state key-value store to instantiate the `QueryStateModel` with.
    */
   constructor(element: HTMLElement, attributes?: IStringMap<string>) {
     let merged = _.extend({}, QueryStateModel.defaultAttributes, attributes);
     super(element, QueryStateModel.ID, merged);
   }
 
   /**
-   * Determine if at least one facet is currently active in the interface (this means that a facet has selected or excluded values)
-   * @returns {boolean}
+   * Validates whether at least one facet is currently active (has selected or excluded values) in the interface.
+   *
+   * @returns {boolean} `true` if at least one facet is active; `false` otherwise.
    */
   public atLeastOneFacetIsActive() {
     return !_.isUndefined(_.find(this.attributes, (value, key: any) => {

src/ui/Base/RegisteredNamedMethods.ts

@@ -120,15 +120,49 @@ Initialization.registerNamedMethod('executeQuery', (element: HTMLElement) => {
 });
 
 /**
- * Perform operation on the state ({@link QueryStateModel} of the interface.<br/>
- * Get the complete {@link QueryStateModel} object: <code>Coveo.state(element)</code><br/>.
- * Get an attribute from the {@link QueryStateModel}: <code>Coveo.state(element, 'q')</code> Can be any attribute.<br/>
- * Set an attribute on the {@link QueryStateModel}: <code>Coveo.state(element, 'q', 'foobar')</code>. Can be any attribute.<br/>
- * Set multiple attribute on the {@link QueryStateModel}: <code>Coveo.state(element, {'q' : 'foobar' , sort : 'relevancy'})</code>. Can be any attribute.<br/>
- * If using the jQuery extension, this is called using <code>$('#root').coveo('state');</code>.
- * @param element The root of the interface for which to access the {@link QueryStateModel}.
- * @param args
- * @returns {any}
+ * Performs read and write operations on the [`QueryStateModel`]{@link QueryStateModel} instance of the search
+ * interface. See [State](https://developers.coveo.com/x/RYGfAQ).
+ *
+ * Can perform the following actions:
+ *
+ * - Get the `QueryStateModel` instance:
+ * ```javascript
+ * Coveo.state(element);
+ * ```
+ *
+ * - Get the value of a single state attribute from the `QueryStateModel` instance:
+ * ```javascript
+ * // You can replace `q` with any registered state attribute.
+ * Coveo.state(element, "q");
+ * ```
+ *
+ * - Set the value of a single state attribute in the `QueryStateModel` instance:
+ * ```javascript
+ * // You can replace `q` with any registered state attribute.
+ * Coveo.state(element, "q", "my new value");
+ * ```
+ *
+ * - Set multiple state attribute values in the `QueryStateModel` instance:
+ * ```javascript
+ * // You can replace `q` and `sort` with any registered state attributes.
+ * Coveo.state(element, {
+ *     "q" : "my new value",
+ *     "sort" : "relevancy"
+ * });
+ * ```
+ *
+ * **Note:**
+ * > When setting one or several state attribute values with this function, you can pass an additional argument to set
+ * > the `silent` attribute to `true` in order to prevent the state change from triggering state change events.
+ * >
+ * > **Example:**
+ * > ```javascript
+ * > Coveo.state(element, "q", "my new value", { "silent" : true });
+ * > ```
+ *
+ * @param element The root of the interface whose `QueryStateModel` instance the function should interact with.
+ * @param args The arguments that determine the action to perform on the `QueryStateModel` instance.
+ * @returns {any} Depends on the action performed.
  */
 export function state(element: HTMLElement, ...args: any[]): any {
   Assert.exists(element);