feat(connector): connectRefinementList jsdoc + start document bool isFirstRendering

Author: Alexandre Stanislawski

src/connectors/refinement-list/connectRefinementList.js

@@ -34,25 +34,30 @@ export const checkUsage = ({attributeName, operator, usageMessage}) => {
 };
 
 /**
- * refinementList connector, allows you to create your own refinement list and completely tune
- * the rendering of it.
- * @name connectRefinementList
- * @TODO: I do not know how to document the dual ()() call in an efficient way with jsDoc that will also be easy
- * to crawl with the doc crawler (maybe re-use exposed props and provided props but rename it for non react people?)
- * @param {function} renderFn The rendering function.
- * @providedProp isFirstRender
- * @providedProp isFromSearch
- * @providedProp createURL
- * @providedProp items
- * @providedProp refine
- * @providedProp searchForItems
- * @providedProp instantSearchInstance
- * @providedProp canRefine
- * @exposedProp attributeName
- * @exposedProp operator
- * @exposedProp limit
- * @exposedProp sortBy
- * @return {[type]}                         [description]
+ * @typedef {Object} RefinementListRenderingOptions
+ * @property {string} attributeName the attribute in the records that are used by the widget
+ * @property {string} operator how the filters are combined together
+ * @property {number} limit the max number of items displayed
+ * @property {string[]} sortBy how the values are ordered
+ */
+
+/**
+ * @typedef {Object} RefinementListRenderingOptions
+ * @property {Object[]} items the list of filtering values returned from Algolia
+ * @property {function} createURL create the next state url
+ * @property {function} refine set the next state url
+ * @property {function} searchForItems search for values inside the list
+ * @property {boolean} isFromSearch indicates if the values are from an index search
+ * @property {boolean} canRefine indicates if a refinement can be applied
+ * @property {InstantSearch} instantSearchInstance the instance of instantsearch on which the widget is attached
+ */
+
+/**
+ * Creates a custom widget for a refinement list.
+ *
+ * @function connectRefinementList
+ * @param {function(RefinementListRenderingOptions, boolean)} renderFn function that renders the refinement list widget
+ * @returns {function(RefinementListWidgetOptions)} a custom refinement list widget factory
  */
 export default function connectRefinementList(renderFn) {
   checkRendering(renderFn, usage);

src/connectors/search-box/connectSearchBox.js

@@ -34,7 +34,7 @@ Full documentation available at https://community.algolia.com/instantsearch.js/c
 
  /**
   * Connects a rendering function with the search box business logic.
-  * @param {function(SearchBoxRenderingOptions)} renderFn function that renders the search box widget
+  * @param {function(SearchBoxRenderingOptions, boolean)} renderFn function that renders the search box widget
   * @return {function(CustomSearchBoxWidgetOptions)} a widget factory for search box widget
   */
 export default function connectSearchBox(renderFn) {

src/connectors/sort-by-selector/connectSortBySelector.js

@@ -34,7 +34,7 @@ Full documentation available at https://community.algolia.com/instantsearch.js/c
 
  /**
   * Connects a rendering function with the sort by selector business logic.
-  * @param {function(SortBySelectorRenderingOptions)} renderFn function that renders the sort by selector widget
+  * @param {function(SortBySelectorRenderingOptions, boolean)} renderFn function that renders the sort by selector widget
   * @return {function(CustomSortBySelectorWidgetOptions)} a widget factory for sort by selector widget
   */
 export default function connectSortBySelector(renderFn) {

src/connectors/star-rating/connectStarRating.js

@@ -36,7 +36,7 @@ Full documentation available at https://community.algolia.com/instantsearch.js/c
 
 /**
  * Connects a rendering function with the star rating business logic.
- * @param {function(StarRatingRenderingOptions)} renderFn function that renders the star rating widget
+ * @param {function(StarRatingRenderingOptions, boolean)} renderFn function that renders the star rating widget
  * @return {function(CustomStarRatingWidgetOptions)} a widget factory for star rating widget
  */
 export default function connectStarRating(renderFn) {

src/connectors/stats/connectStats.js

@@ -28,7 +28,7 @@ Full documentation available at https://community.algolia.com/instantsearch.js/c
 
 /**
  * Connects a rendering function with the stats business logic.
- * @param {function(StatsRenderingOptions)} renderFn function that renders the stats widget
+ * @param {function(StatsRenderingOptions, boolean)} renderFn function that renders the stats widget
  * @return {function} a widget factory for stats widget
  */
 export default function connectStats(renderFn) {

src/connectors/toggle/connectToggle.js

@@ -40,7 +40,7 @@ Full documentation available at https://community.algolia.com/instantsearch.js/c
 
 /**
  * Connects a rendering function with the toggle business logic.
- * @param {function(ToggleRenderingOptions)} renderFn function that renders the toggle widget
+ * @param {function(ToggleRenderingOptions, boolean)} renderFn function that renders the toggle widget
  * @return {function(CustomToggleWidgetOptions)} a widget factory for toggle widget
  */
 export default function connectToggle(renderFn) {