Apply suggestions from code review

Co-authored-by: James Fan <james@somewhatstrange.com>

modules/preview-react/radio/lib/RadioGroup.tsx

@@ -20,14 +20,12 @@ export interface RadioGroupProps extends Themeable, ExtractProps<typeof Flex, ne
 }
 
 /**
- * When you have a group of radio inputs, use RadioGroup.
- *
- * **Note:** You must provide a `name`. This ensures that each `input` has a `name` attribute which groups the inputs.
+* Use `RadioGroup` to group a collection of `RadioGroup.Radio` components under a common `name`.
  *
  * ```tsx
  * <RadioGroup name="pizza-crust" value="thin">
- *    <RadioGroup.Radio value="deep-dish">Deep Dish</RadioGroup.Radio>
- *    <RadioGroup.Radio value="thin">Thin</RadioGroup.Radio>
+ *   <RadioGroup.Radio value="deep-dish">Deep Dish</RadioGroup.Radio>
+ *   <RadioGroup.Radio value="thin">Thin</RadioGroup.Radio>
  * </RadioGroup>
  * ```
  */
@@ -36,27 +34,27 @@ export const RadioGroup = createContainer(Flex)({
   modelHook: useRadioModel,
   subComponents: {
     /**
-     * This a simplified component that renders a `label` and `input` element with children being the text associated to the radio input.
-     * In most cases you will use this component.
+     * `RadioGroup.Radio` renders an `<input type="radio" />` and its associated `<label>` (using `children` as the label's contents).
+     * This component should satisfy most use cases; use `RadioGroup.Label` if you require more flexibility.
      *
      * ```tsx
      * <RadioGroup name="pizza-crust" value="thin">
-     *    <RadioGroup.Radio value="deep-dish">Deep Dish</RadioGroup.Radio>
-     *    <RadioGroup.Radio value="thin">Thin</RadioGroup.Radio>
+     *   <RadioGroup.Radio value="deep-dish">Deep Dish</RadioGroup.Radio>
+     *   <RadioGroup.Radio value="thin">Thin</RadioGroup.Radio>
      * </RadioGroup>
      * ```
      */
     Radio: Radio,
     /**
-     * Use this if you want more control over styling the text and input.
-     * This will render a `label` element that wraps an `input` and `span`.
+     * Use `RadioGroup.Label` instead of `RadioGroup.Radio` if you need direct access to the label and the radio input.
+     * This will render a `<label>` that wraps an `<input type="radio" />` and a `<span>` for the label text.
      *
      * ```tsx
-     * <RadioGroup name"pizza-crust"" value="deep-dish">
-     *    <RadioGroup.Label>
-     *      <RadioGroup.Label.Input checked value="deep-dish" />
-     *      <RadioGroup.Label.Text>Deep Dish</RadioGroup.Label.Text>
-     *    </RadioGroup.Label>
+     * <RadioGroup name"pizza-crust" value="deep-dish">
+     *   <RadioGroup.Label>
+     *     <RadioGroup.Label.Input checked value="deep-dish" />
+     *     <RadioGroup.Label.Text>Deep Dish</RadioGroup.Label.Text>
+     *   </RadioGroup.Label>
      * </RadioGroup>
      * ```
      */

modules/preview-react/radio/lib/RadioLabel.tsx

@@ -28,7 +28,31 @@ export const RadioLabel = createSubcomponent('label')({
   displayName: 'Radio.Label',
   modelHook: useRadioModel,
   subComponents: {
+    /**
+     * Use `RadioGroup.Label.Input` within a `RadioGroup.Label` to render the input portion of a radio button.
+     *
+     * ```tsx
+     * <RadioGroup name"pizza-crust" value="deep-dish">
+     *   <RadioGroup.Label>
+     *     <RadioGroup.Label.Input value="deep-dish" />
+     *     <RadioGroup.Label.Text>Deep Dish</RadioGroup.Label.Text>
+     *   </RadioGroup.Label>
+     * </RadioGroup>
+     * ```
+     */
     Input: RadioInput,
+    /**
+     * Use `RadioGroup.Label.Text` within a `RadioGroup.Label` to render the label text portion of a radio button.
+     *
+     * ```tsx
+     * <RadioGroup name"pizza-crust" value="deep-dish">
+     *   <RadioGroup.Label>
+     *     <RadioGroup.Label.Input value="deep-dish" />
+     *     <RadioGroup.Label.Text>Deep Dish</RadioGroup.Label.Text>
+     *   </RadioGroup.Label>
+     * </RadioGroup>
+     * ```
+     */
     Text: RadioText,
   },
 })<RadioLabelProps>(

modules/preview-react/radio/stories/radio.stories.mdx

@@ -79,29 +79,28 @@ Use error when the selection is no longer valid.
 
 ### Inverse
 
-In cases where you need to render radio groups on dark backgrounds, you can set the `variant` prop
-to `inverse` on the `RadioGroup.Radio`. This will change the colors on the text and input so that
-they can be used on different backgrounds.
+Set the `variant` prop of `RadioGroup.Radio` to `inverse` to ensure proper contrast on dark
+backgrounds.
 
 <ExampleCodeBlock code={Inverse} />
 
-### Radio Buttons with No Values
+### Radio Group with No Value
 
-The `value` prop may be omitted from `RadioGroup` to render the group with no selected radios.
+Omit the `value` prop from `RadioGroup` to render the group with no selected `RadioGroup.Radio`.
 
 <ExampleCodeBlock code={NoValue} />
 
 ### Ref Forwarding
 
-Radio buttons supports [ref forwarding](https://reactjs.org/docs/forwarding-refs.html). It will
+`RadioGroup.Radio` supports [ref forwarding](https://reactjs.org/docs/forwarding-refs.html). It will
 forward `ref` to its underlying `<input type="radio">` element.
 
 <ExampleCodeBlock code={RefForwarding} />
 
 ### Label Position
 
-Set the `labelPosition` prop of the wrapping Form Field to designate the position of the label
-relative to the Radio Group. `labelPosition` accepts the following values:
+Set the `labelPosition` prop of the wrapping `FormField` to designate the position of the label
+relative to the `RadioGroup`. `labelPosition` accepts the following values:
 
 - `FormField.LabelPosition.Top` (Default)
 - `FormField.LabelPosition.Left`