docs(dynamicWidgets): implement tsdoc for parameters (#4920)

* docs(dynamicWidgets): implement tsdoc for parameters * Apply suggestions from code review Co-authored-by: Sarah Dayan <[email protected]> Co-authored-by: Sarah Dayan <[email protected]>
algolia · Oct 13, 2021 · 041b70e · 041b70e
1 parent 76afacb
commit 041b70e
Show file tree

Hide file tree

Showing 2 changed files with 37 additions and 3 deletions.
diff --git a/src/connectors/dynamic-widgets/connectDynamicWidgets.ts b/src/connectors/dynamic-widgets/connectDynamicWidgets.ts
@@ -17,8 +17,24 @@ export type DynamicWidgetsRenderState = {
 };
 
 export type DynamicWidgetsConnectorParams = {
+  /**
+   * An array of widgets, displayed in the order defined by `facetOrdering`.
+   */
   widgets: Widget[];
-  fallbackWidget?(args: { attribute: string }): Widget;
+
+  /**
+   * Function to return a fallback widget when an attribute isn't found in
+   * `widgets`.
+   */
+  fallbackWidget?(args: {
+    /** The attribute name to create a widget for. */
+    attribute: string;
+  }): Widget;
+
+  /**
+   * Function to transform the items to render.
+   * The function also exposes the full search response.
+   */
   transformItems?(
     items: string[],
     metadata: { results: SearchResults }

diff --git a/src/widgets/dynamic-widgets/dynamic-widgets.ts b/src/widgets/dynamic-widgets/dynamic-widgets.ts
@@ -17,9 +17,27 @@ const withUsage = createDocumentationMessageGenerator({
 const suit = component('DynamicWidgets');
 
 export type DynamicWidgetsWidgetParams = {
-  container: HTMLElement | string;
+  /**
+   * CSS Selector or HTMLElement to insert the widget.
+   */
+  container: string | HTMLElement;
+
+  /**
+   * An array of widget creator functions, displayed in the order defined by
+   * `facetOrdering`.
+   */
   widgets: Array<(container: HTMLElement) => Widget>;
-  fallbackWidget?(args: { attribute: string; container: HTMLElement }): Widget;
+
+  /**
+   * Function to return a fallback widget when an attribute isn't found in
+   * `widgets`.
+   */
+  fallbackWidget?(args: {
+    /** The attribute name to create a widget for. */
+    attribute: string;
+    /** CSS Selector or HTMLElement to insert the widget */
+    container: HTMLElement;
+  }): Widget;
 };
 
 export type DynamicWidgetsWidget = WidgetFactory<