Migrate/audit JSDoc on public APIs (Components) (#57382)

Summary:
Pull Request resolved: #57382

**Context**

Strict TypeScript API readiness: High quality inline docs should reach users via TypeScript in their IDEs.

**This diff**

I asked Claude to crawl reactnative.dev and insert JSDoc comments into our core components, based on some manual-pass starting points.

This is also a quality pass on all modules touched, standardising JSDoc use, and in some cases merging/removing redundant information (preferring the docs we’ve maintained more carefully on the website).

Commit 1 of 2 (Components).

Replaces #57380.

Changelog: [Internal]

___

Differential Revision: D110195869

fbshipit-source-id: a60cded5a0c599810c80d174b7de085903cd6701

Author: huntie

packages/react-native/Libraries/Components/Button.js

@@ -30,262 +30,170 @@ import * as React from 'react';
 /** @build-types emit-as-interface Uniwind compatibility */
 export type ButtonProps = Readonly<{
   /**
-    Text to display inside the button. On Android the given title will be
-    converted to the uppercased form.
+   * Text to display inside the button. On Android the given title will be
+   * converted to the uppercased form.
    */
   title: string,
 
   /**
-    Handler to be called when the user taps the button. The first function
-    argument is an event in form of [GestureResponderEvent](pressevent).
+   * Handler called when the user taps the button.
    */
   onPress?: (event?: GestureResponderEvent) => unknown,
 
   /**
-    If `true`, doesn't play system sound on touch.
-
-    @platform android
-
-    @default false
+   * If `true`, doesn't play system sound on touch.
+   *
+   * @platform android
+   *
+   * @default `false`
    */
   touchSoundDisabled?: ?boolean,
 
   /**
-    Color of the text (iOS), or background color of the button (Android).
-
-    @default {@platform android} '#2196F3'
-    @default {@platform ios} '#007AFF'
+   * Color of the text (iOS), or background color of the button (Android).
+   *
+   * @default {@platform android} `'#2196F3'`
+   * @default {@platform ios} `'#007AFF'`
    */
   color?: ?ColorValue,
 
   /**
-    TV preferred focus.
-
-    @platform tv
-
-    @default false
-    @deprecated Use `focusable` instead
+   * TV preferred focus.
+   *
+   * @platform tv
+   *
+   * @default `false`
+   * @deprecated Use `focusable` instead
    */
   hasTVPreferredFocus?: ?boolean,
 
   /**
-    Designates the next view to receive focus when the user navigates down. See
-    the [Android documentation][android:nextFocusDown].
-
-    [android:nextFocusDown]:
-    https://developer.android.com/reference/android/view/View.html#attr_android:nextFocusDown
-
-    @platform android, tv
+   * Designates the next view to receive focus when the user navigates down. See
+   * the [Android documentation][android:nextFocusDown].
+   *
+   * [android:nextFocusDown]:
+   * https://developer.android.com/reference/android/view/View.html#attr_android:nextFocusDown
+   *
+   * @platform android, tv
    */
   nextFocusDown?: ?number,
 
   /**
-    Designates the next view to receive focus when the user navigates forward.
-    See the [Android documentation][android:nextFocusForward].
-
-    [android:nextFocusForward]:
-    https://developer.android.com/reference/android/view/View.html#attr_android:nextFocusForward
-
-    @platform android, tv
+   * Designates the next view to receive focus when the user navigates forward.
+   * See the [Android documentation][android:nextFocusForward].
+   *
+   * [android:nextFocusForward]:
+   * https://developer.android.com/reference/android/view/View.html#attr_android:nextFocusForward
+   *
+   * @platform android, tv
    */
   nextFocusForward?: ?number,
 
   /**
-    Designates the next view to receive focus when the user navigates left. See
-    the [Android documentation][android:nextFocusLeft].
-
-    [android:nextFocusLeft]:
-    https://developer.android.com/reference/android/view/View.html#attr_android:nextFocusLeft
-
-    @platform android, tv
+   * Designates the next view to receive focus when the user navigates left. See
+   * the [Android documentation][android:nextFocusLeft].
+   *
+   * [android:nextFocusLeft]:
+   * https://developer.android.com/reference/android/view/View.html#attr_android:nextFocusLeft
+   *
+   * @platform android, tv
    */
   nextFocusLeft?: ?number,
 
   /**
-    Designates the next view to receive focus when the user navigates right. See
-    the [Android documentation][android:nextFocusRight].
-
-    [android:nextFocusRight]:
-    https://developer.android.com/reference/android/view/View.html#attr_android:nextFocusRight
-
-    @platform android, tv
+   * Designates the next view to receive focus when the user navigates right. See
+   * the [Android documentation][android:nextFocusRight].
+   *
+   * [android:nextFocusRight]:
+   * https://developer.android.com/reference/android/view/View.html#attr_android:nextFocusRight
+   *
+   * @platform android, tv
    */
   nextFocusRight?: ?number,
 
   /**
-    Designates the next view to receive focus when the user navigates up. See
-    the [Android documentation][android:nextFocusUp].
-
-    [android:nextFocusUp]:
-    https://developer.android.com/reference/android/view/View.html#attr_android:nextFocusUp
-
-    @platform android, tv
+   * Designates the next view to receive focus when the user navigates up. See
+   * the [Android documentation][android:nextFocusUp].
+   *
+   * [android:nextFocusUp]:
+   * https://developer.android.com/reference/android/view/View.html#attr_android:nextFocusUp
+   *
+   * @platform android, tv
    */
   nextFocusUp?: ?number,
 
   /**
-    Text to display for blindness accessibility features.
+   * Text to display for blindness accessibility features.
    */
   accessibilityLabel?: ?string,
+
   /**
-   * Alias for accessibilityLabel  https://reactnative.dev/docs/view#accessibilitylabel
-   * https://github.com/facebook/react-native/issues/34424
+   * Alias for `accessibilityLabel`.
    */
   'aria-label'?: ?string,
-  /**
-    If `true`, disable all interactions for this component.
 
-    @default false
+  /**
+   * If `true`, disable all interactions for this component.
+   *
+   * @default `false`
    */
   disabled?: ?boolean,
 
-  /**
-    Used to locate this view in end-to-end tests.
-   */
   testID?: ?string,
 
-  /**
-   * Accessibility props.
-   */
   accessible?: ?boolean,
   accessibilityActions?: ?ReadonlyArray<AccessibilityActionInfo>,
   onAccessibilityAction?: ?(event: AccessibilityActionEvent) => unknown,
   accessibilityState?: ?AccessibilityState,
 
   /**
-   * alias for accessibilityState
-   *
-   * see https://reactnative.dev/docs/accessibility#accessibilitystate
+   * Alias for `accessibilityState`.
    */
   'aria-busy'?: ?boolean,
   'aria-checked'?: ?boolean | 'mixed',
   'aria-disabled'?: ?boolean,
   'aria-expanded'?: ?boolean,
   'aria-selected'?: ?boolean,
 
-  /**
-   * [Android] Controlling if a view fires accessibility events and if it is reported to accessibility services.
-   */
   importantForAccessibility?: ?('auto' | 'yes' | 'no' | 'no-hide-descendants'),
   accessibilityHint?: ?string,
+
+  /**
+   * A BCP 47 language tag for the screen reader to use when reading text
+   * content.
+   *
+   * @platform ios
+   */
   accessibilityLanguage?: ?Stringish,
 }>;
 
-/**
-  A basic button component that should render nicely on any platform. Supports a
-  minimal level of customization.
-
-  If this button doesn't look right for your app, you can build your own button
-  using [TouchableOpacity](touchableopacity) or
-  [TouchableWithoutFeedback](touchablewithoutfeedback). For inspiration, look at
-  the [source code for this button component][button:source]. Or, take a look at
-  the [wide variety of button components built by the community]
-  [button:examples].
-
-  [button:source]:
-  https://github.com/facebook/react-native/blob/HEAD/Libraries/Components/Button.js
-
-  ```jsx
-  <Button
-    onPress={onPressLearnMore}
-    title="Learn More"
-    color="#841584"
-    accessibilityLabel="Learn more about this purple button"
-  />
-  ```
-
-  ```SnackPlayer name=Button%20Example
-  import React from 'react';
-  import { StyleSheet, Button, View, SafeAreaView, Text, Alert } from 'react-native';
-
-  const Separator = () => (
-    <View style={styles.separator} />
-  );
-
-  const App = () => (
-    <SafeAreaView style={styles.container}>
-      <View>
-        <Text style={styles.title}>
-          The title and onPress handler are required. It is recommended to set accessibilityLabel to help make your app usable by everyone.
-        </Text>
-        <Button
-          title="Press me"
-          onPress={() => Alert.alert('Simple Button pressed')}
-        />
-      </View>
-      <Separator />
-      <View>
-        <Text style={styles.title}>
-          Adjust the color in a way that looks standard on each platform. On  iOS, the color prop controls the color of the text. On Android, the color adjusts the background color of the button.
-        </Text>
-        <Button
-          title="Press me"
-          color="#f194ff"
-          onPress={() => Alert.alert('Button with adjusted color pressed')}
-        />
-      </View>
-      <Separator />
-      <View>
-        <Text style={styles.title}>
-          All interaction for the component are disabled.
-        </Text>
-        <Button
-          title="Press me"
-          disabled
-          onPress={() => Alert.alert('Cannot press this one')}
-        />
-      </View>
-      <Separator />
-      <View>
-        <Text style={styles.title}>
-          This layout strategy lets the title define the width of the button.
-        </Text>
-        <View style={styles.fixToText}>
-          <Button
-            title="Left button"
-            onPress={() => Alert.alert('Left button pressed')}
-          />
-          <Button
-            title="Right button"
-            onPress={() => Alert.alert('Right button pressed')}
-          />
-        </View>
-      </View>
-    </SafeAreaView>
-  );
-
-  const styles = StyleSheet.create({
-    container: {
-      flex: 1,
-      justifyContent: 'center',
-      marginHorizontal: 16,
-    },
-    title: {
-      textAlign: 'center',
-      marginVertical: 8,
-    },
-    fixToText: {
-      flexDirection: 'row',
-      justifyContent: 'space-between',
-    },
-    separator: {
-      marginVertical: 8,
-      borderBottomColor: '#737373',
-      borderBottomWidth: StyleSheet.hairlineWidth,
-    },
-  });
-
-  export default App;
-  ```
- */
-
 const NativeTouchable:
   | typeof TouchableNativeFeedback
   | typeof TouchableOpacity =
   Platform.OS === 'android' ? TouchableNativeFeedback : TouchableOpacity;
 
 export type ButtonInstance = React.ElementRef<typeof NativeTouchable>;
 
+/**
+ * A basic button component that should render nicely on any platform. Supports a
+ * minimal level of customization.
+ *
+ * If this button doesn't look right for your app, you can build your own button
+ * using `Pressable`.
+ *
+ * Example:
+ *
+ * ```tsx
+ * <Button
+ *   onPress={onPressLearnMore}
+ *   title="Learn More"
+ *   color="#841584"
+ *   accessibilityLabel="Learn more about this purple button"
+ * />
+ * ```
+ *
+ * @see https://reactnative.dev/docs/button
+ */
 const Button: component(
   ref?: React.RefSetter<ButtonInstance>,
   ...props: ButtonProps