From da61164df8c9c58b678cd75468c90a3b0d439ac9 Mon Sep 17 00:00:00 2001
From: Frederic Beaudoin <fbeaudoin@coveo.com>
Date: Tue, 21 Mar 2017 10:35:20 -0400
Subject: [PATCH] DOC-635 - Added some info about FacetRange VS query function
 generated fields - Also revised the IRangeValue documentation

---
 src/rest/RangeValue.ts          | 20 +++++++++++++++-----
 src/ui/FacetRange/FacetRange.ts | 33 ++++++++++++++++++---------------
 2 files changed, 33 insertions(+), 20 deletions(-)

diff --git a/src/rest/RangeValue.ts b/src/rest/RangeValue.ts
index 292d491c47..920bab296d 100644
--- a/src/rest/RangeValue.ts
+++ b/src/rest/RangeValue.ts
@@ -1,21 +1,31 @@
 /**
- * Describe a single rangle value in a group by
+ * The IRangeValue interface describes a single range of values in a group by clause.
  */
 export interface IRangeValue {
+
   /**
-   * Start of the range.
+   * Specifies the start of the range.
+   *
+   * E.g., `0`
    */
   start?: any;
+
   /**
-   * End of the range
+   * Specifies the end of the range.
+   *
+   * E.g., `500`
    */
   end?: any;
+
   /**
-   * Label to generate for this range
+   * Specifies the label to generate for this range.
+   *
+   * E.g., `0 - 500`
    */
   label?: string;
+
   /**
-   * Is the end parameter included or excluded in this range.
+   * Specifies whether to include the value of the [end]{@link IRangeValue.end} property in this range.
    */
   endInclusive?: boolean;
 }
diff --git a/src/ui/FacetRange/FacetRange.ts b/src/ui/FacetRange/FacetRange.ts
index b89b2fcdbd..10be3c3718 100644
--- a/src/ui/FacetRange/FacetRange.ts
+++ b/src/ui/FacetRange/FacetRange.ts
@@ -21,7 +21,8 @@ export interface IFacetRangeOptions extends IFacetOptions {
  * from the results of the current query.
  *
  * This component inherits from the Facet component. Thus, any option available for a Facet component is also available
- * for a FacetRange component.
+ * for a FacetRange component. This also implies that you must specify a [field]{@link Facet.options.field} value for
+ * this component to work.
  */
 export class FacetRange extends Facet implements IComponentBindings {
   static ID = 'FacetRange';
@@ -34,7 +35,7 @@ export class FacetRange extends Facet implements IComponentBindings {
   static options: IFacetRangeOptions = {
 
     /**
-     * Specifies whether the field for which you require a range is a date field.
+     * Specifies whether the field for which you require ranges is a date field.
      *
      * This allows the component to correctly build the outgoing {@link IGroupByRequest}.
      *
@@ -51,39 +52,41 @@ export class FacetRange extends Facet implements IComponentBindings {
      * **Example:**
      *
      * ```javascript
-     * var myRanges = [{
+     * var myRanges = [
+     *   {
      *      start: 0,
      *      end: 100,
      *      label: "0 - 100",
      *      endInclusive: false
-     *    }, {
+     *    },
+     *    {
      *      start: 100,
      *      end: 200,
      *      label: "100 - 200",
      *      endInclusive: false
-     *    }, {
+     *    },
+     *    {
      *      start: 200,
      *      end: 300,
      *      label: "200 - 300",
      *      endInclusive: false
-     * }]
-     *
-     * // You can call the init script using "pure" JavaScript:
-     * Coveo.init(document.querySelector('#search'), {
-     *    FacetRange : {
-     *        ranges : myRanges
      *    }
-     * })
+     * ]
      *
-     * // Or you can call the init script using the jQuery extension:
-     * $("#search").coveo("init", {
+     * Coveo.init(document.querySelector('#search'), {
      *    FacetRange : {
      *        ranges : myRanges
      *    }
      * })
      * ```
      *
-     * Default value is `null` and the index will automatically generate ranges.
+     * **Note:**
+     * > Ranges can overlap.
+     *
+     * By default, the index automatically generates the ranges. However, the index cannot automatically generate the
+     * ranges if the [field]{@link Facet.options.field} you specify for the FacetRange component is generated by a query
+     * function (see [Query Function](https://developers.coveo.com/x/XQCq)). When this is the case, you must specify the
+     * ranges at query time.
      */
     ranges: ComponentOptions.buildCustomOption<IRangeValue[]>(() => {
       return null;