Merge pull request #3924 from theosherry/SelectField_docs

[SelectField] Add callback signatures to docs; improve other props.

src/SelectField/SelectField.js

@@ -23,74 +23,82 @@ class SelectField extends Component {
     /**
      * If true, the width will automatically be set according to the
      * items inside the menu.
-     * To control this width in css instead, leave this prop to `false`.
+     * To control the width in CSS instead, leave this prop set to `false`.
      */
     autoWidth: PropTypes.bool,
     /**
-     * The `MenuItem` elements to populate the `Menu` with.
-     * If the MenuItems have the prop `label` that value will
-     * be used to render the representation of that
-     * item within the field.
+     * The `MenuItem` elements to populate the select field with.
+     * If the menu items have a `label` prop, that value will
+     * represent the selected menu item in the rendered select field.
      */
     children: PropTypes.node,
     /**
-     * Disables the select field if set to true.
+     * If true, the select field will be disabled.
      */
     disabled: PropTypes.bool,
     /**
-     * The style object to use to override error styles.
+     * Override the inline-styles of the error element.
      */
     errorStyle: PropTypes.object,
     /**
      * The error content to display.
      */
     errorText: PropTypes.node,
     /**
-     * The style object to use to override floating label styles.
+     * Override the inline-styles of the floating label.
      */
     floatingLabelStyle: PropTypes.object,
     /**
-     * The content to use for the floating label element.
+     * The content of the floating label.
      */
     floatingLabelText: PropTypes.node,
     /**
-     * If true, the field receives the property width 100%.
+     * If true, the select field will take up the full width of its container.
      */
     fullWidth: PropTypes.bool,
     /**
-     * The style object to use to override hint styles.
+     * Override the inline-styles of the hint element.
      */
     hintStyle: PropTypes.object,
     /**
      * The hint content to display.
      */
     hintText: PropTypes.node,
     /**
-     * Overrides the styles of the icon element.
+     * Override the inline-styles of the icon element.
      */
     iconStyle: PropTypes.object,
     /**
      * The id prop for the text field.
      */
     id: PropTypes.string,
     /**
-     * Overrides the styles of label when the `SelectField` is inactive.
+     * Override the label style when the select field is inactive.
      */
     labelStyle: PropTypes.object,
     /**
-     * Callback function that is fired when the `SelectField` loses focus.
+     * Callback function fired when the select field loses focus.
+     *
+     * @param {object} event `blur` event targeting the select field.
      */
     onBlur: PropTypes.func,
     /**
-     * Callback function that is fired when the value changes.
+     * Callback function fired when a menu item is selected.
+     *
+     * @param {object} event TouchTap event targeting the menu item
+     * that was selected.
+     * @param {number} key The index of the selected menu item.
+     * @param {any} payload The `value` prop of the selected menu item.
      */
     onChange: PropTypes.func,
     /**
-     * Callback function that is fired when the `SelectField` gains focus.
+     * Callback function fired when the select field gains focus.
+     *
+     * @param {object} event `focus` event targeting the select field.
      */
     onFocus: PropTypes.func,
     /**
-     * The style object to use to override the `DropDownMenu`.
+     * Override the inline-styles of the underlying `DropDownMenu` element.
      */
     selectFieldRoot: PropTypes.object, // Must be changed!
 
@@ -99,15 +107,17 @@ class SelectField extends Component {
      */
     style: PropTypes.object,
     /**
-     * Override the inline-styles of the underline element when disabled.
+     * Override the inline-styles of the underline element when the select
+     * field is disabled.
      */
     underlineDisabledStyle: PropTypes.object,
     /**
-     * Override the inline-styles of the underline element when focused.
+     * Override the inline-styles of the underline element when the select field
+     * is focused.
      */
     underlineFocusStyle: PropTypes.object,
     /**
-     * Overrides the styles of the underline element.
+     * Override the inline-styles of the underline element.
      */
     underlineStyle: PropTypes.object,
     /**