Improve documentation and clarity of Toolbar (#6308)

components/toolbar/index.js

@@ -10,6 +10,36 @@ import { flatMap } from 'lodash';
 import './style.scss';
 import IconButton from '../icon-button';
 
+/**
+ * Renders a toolbar with controls.
+ *
+ * The `controls` prop accepts an array of sets. A set is an array of controls.
+ * Controls have the following shape:
+ *
+ * ```
+ * {
+ *   icon: string,
+ *   title: string,
+ *   subscript: string,
+ *   onClick: Function,
+ *   isActive: boolean,
+ *   isDisabled: boolean
+ * }
+ * ```
+ *
+ * For convenience it is also possible to pass only an array of controls. It is
+ * then assumed this is the only set.
+ *
+ * Either `controls` or `children` is required, otherwise this components
+ * renders nothing.
+ *
+ * @param {?Array}        controls  The controls to render in this toolbar.
+ * @param {?ReactElement} children  Any other things to render inside the
+ *                                  toolbar besides the controls.
+ * @param {?string}       className Class to set on the container div.
+ *
+ * @return {ReactElement} The rendered toolbar.
+ */
 function Toolbar( { controls = [], children, className } ) {
 	if (
 		( ! controls || ! controls.length ) &&
@@ -26,11 +56,11 @@ function Toolbar( { controls = [], children, className } ) {
 
 	return (
 		<div className={ classnames( 'components-toolbar', className ) }>
-			{ flatMap( controlSets, ( controlSet, setIndex ) => (
-				controlSet.map( ( control, controlIndex ) => (
+			{ flatMap( controlSets, ( controlSet, indexOfSet ) => (
+				controlSet.map( ( control, indexOfControl ) => (
 					<div
-						key={ [ setIndex, controlIndex ].join() }
-						className={ setIndex > 0 && controlIndex === 0 ? 'has-left-divider' : null }
+						key={ [ indexOfSet, indexOfControl ].join() }
+						className={ indexOfSet > 0 && indexOfControl === 0 ? 'has-left-divider' : null }
 					>
 						<IconButton
 							icon={ control.icon }

components/toolbar/test/index.js

@@ -63,14 +63,18 @@ describe( 'Toolbar', () => {
 
 		it( 'should render a nested list of controls with separator between', () => {
 			const controls = [
-				[ {
-					icon: 'wordpress',
-					title: 'WordPress',
-				} ],
-				[ {
-					icon: 'wordpress',
-					title: 'WordPress',
-				} ],
+				[ // First set
+					{
+						icon: 'wordpress',
+						title: 'WordPress',
+					},
+				],
+				[ // Second set
+					{
+						icon: 'wordpress',
+						title: 'WordPress',
+					},
+				],
 			];
 
 			const toolbar = shallow( <Toolbar controls={ controls } /> );