Improve generated API doc comments (match baseline) (#57380)

Summary:
Pull Request resolved: #57380

Surface documentation on hover for more APIs in the generated TypeScript types (`types_generated/`).

**Changes**

- Fix doc comments that were previously detached from the intended symbol (`Modal`, `Button`, `TextInput`, `ScrollView`, and others).
- Migrate doc comments/extra detail present in the legacy hand-written `.d.ts` files but missing from Flow source.
    - (**Note**: The quality of these vary — but lift the equivalent current state into Flow land.)
- Reformat malformed JSDoc comments across the codebase.

Comments only — no code or type changes. Does not look to audit/improve doc comments beyond today's manual TS API baseline.

Changelog: [Internal]

Differential Revision: D109316360

Author: huntie

packages/react-native/Libraries/ActionSheetIOS/ActionSheetIOS.js

@@ -38,6 +38,10 @@ export type ShareActionSheetIOSOptions = Readonly<{
   tintColor?: ?number,
   cancelButtonTintColor?: ?number,
   disabledButtonTintColor?: ?number,
+  /**
+   * The activities to exclude from the ActionSheet.
+   * For example: ['com.apple.UIKit.activity.PostToTwitter']
+   */
   excludedActivityTypes?: ?Array<string>,
   userInterfaceStyle?: ?string,
 }>;

packages/react-native/Libraries/Alert/Alert.js

@@ -57,6 +57,33 @@ export type AlertOptions = {
  * alerts. On iOS, you can show an alert that prompts the user to enter
  * some information.
  *
+ * ## iOS
+ *
+ * On iOS you can specify any number of buttons. Each button can optionally
+ * specify a style, which is one of 'default', 'cancel' or 'destructive'.
+ *
+ * ## Android
+ *
+ * On Android at most three buttons can be specified. Android has a concept
+ * of a neutral, negative and a positive button:
+ *
+ *   - If you specify one button, it will be the 'positive' one (such as 'OK')
+ *   - Two buttons mean 'negative', 'positive' (such as 'Cancel', 'OK')
+ *   - Three buttons mean 'neutral', 'negative', 'positive' (such as 'Later', 'Cancel', 'OK')
+ *
+ * ```
+ * // Works on both iOS and Android
+ * Alert.alert(
+ *   'Alert Title',
+ *   'My Alert Msg',
+ *   [
+ *     {text: 'Ask me later', onPress: () => console.log('Ask me later pressed')},
+ *     {text: 'Cancel', onPress: () => console.log('Cancel Pressed'), style: 'cancel'},
+ *     {text: 'OK', onPress: () => console.log('OK Pressed')},
+ *   ]
+ * )
+ * ```
+ *
  * See https://reactnative.dev/docs/alert
  */
 class Alert {

packages/react-native/Libraries/Animated/AnimatedExports.js

@@ -24,21 +24,43 @@ const Animated: typeof AnimatedImplementation = Platform.isDisableAnimations
   : AnimatedImplementation;
 
 export default {
+  /**
+   * FlatList and SectionList infer generic Type defined under their `data` and `section` props.
+   */
   get FlatList(): AnimatedFlatList<any> {
     return require('./components/AnimatedFlatList').default;
   },
+  /**
+   * Animated variants of the basic native views. Accepts Animated.Value for
+   * props and style.
+   */
   get Image(): AnimatedImage {
     return require('./components/AnimatedImage').default;
   },
+  /**
+   * Animated variants of the basic native views. Accepts Animated.Value for
+   * props and style.
+   */
   get ScrollView(): AnimatedScrollView {
     return require('./components/AnimatedScrollView').default;
   },
+  /**
+   * FlatList and SectionList infer generic Type defined under their `data` and `section` props.
+   */
   get SectionList(): AnimatedSectionList<any, any> {
     return require('./components/AnimatedSectionList').default;
   },
+  /**
+   * Animated variants of the basic native views. Accepts Animated.Value for
+   * props and style.
+   */
   get Text(): AnimatedText {
     return require('./components/AnimatedText').default;
   },
+  /**
+   * Animated variants of the basic native views. Accepts Animated.Value for
+   * props and style.
+   */
   get View(): AnimatedView {
     return require('./components/AnimatedView').default;
   },

packages/react-native/Libraries/Animated/AnimatedImplementation.js

@@ -40,8 +40,29 @@ import AnimatedValue from './nodes/AnimatedValue';
 import AnimatedValueXY from './nodes/AnimatedValueXY';
 
 export type CompositeAnimation = {
+  /**
+   * Animations are started by calling start() on your animation.
+   * start() takes a completion callback that will be called when the
+   * animation is done or when the animation is done because stop() was
+   * called on it before it could finish.
+   *
+   * @param callback - Optional function that will be called
+   *      after the animation finished running normally or when the animation
+   *      is done because stop() was called on it before it could finish
+   *
+   * @example
+   *   Animated.timing({}).start(({ finished }) => {
+   *    // completion callback
+   *   });
+   */
   start: (callback?: ?EndCallback, isLooping?: boolean) => void,
+  /**
+   * Stops any running animation.
+   */
   stop: () => void,
+  /**
+   * Stops any running animation and resets the value to its original.
+   */
   reset: () => void,
   _startNativeLoop: (iterations?: number) => void,
   _isUsingNativeDriver: () => boolean,
@@ -621,21 +642,104 @@ export default {
    * See https://reactnative.dev/docs/animated#node
    */
   Node: AnimatedNode,
+  /**
+   * Animates a value from an initial velocity to zero based on a decay
+   * coefficient.
+   */
   decay: decayImpl,
+  /**
+   * Animates a value along a timed easing curve.  The `Easing` module has tons
+   * of pre-defined curves, or you can use your own function.
+   */
   timing: timingImpl,
+  /**
+   * Spring animation based on Rebound and Origami.  Tracks velocity state to
+   * create fluid motions as the `toValue` updates, and can be chained together.
+   */
   spring: springImpl,
+  /**
+   * Creates a new Animated value composed from two Animated values added
+   * together.
+   */
   add: addImpl,
+  /**
+   * Creates a new Animated value composed by subtracting the second Animated
+   * value from the first Animated value.
+   */
   subtract: subtractImpl,
+  /**
+   * Creates a new Animated value composed by dividing the first Animated
+   * value by the second Animated value.
+   */
   divide: divideImpl,
+  /**
+   * Creates a new Animated value composed from two Animated values multiplied
+   * together.
+   */
   multiply: multiplyImpl,
+  /**
+   * Creates a new Animated value that is the (non-negative) modulo of the
+   * provided Animated value
+   */
   modulo: moduloImpl,
+  /**
+   * Create a new Animated value that is limited between 2 values. It uses the
+   * difference between the last value so even if the value is far from the bounds
+   * it will start changing when the value starts getting closer again.
+   * (`value = clamp(value + diff, min, max)`).
+   *
+   * This is useful with scroll events, for example, to show the navbar when
+   * scrolling up and to hide it when scrolling down.
+   */
   diffClamp: diffClampImpl,
+  /**
+   * Starts an animation after the given delay.
+   */
   delay: delayImpl,
+  /**
+   * Starts an array of animations in order, waiting for each to complete
+   * before starting the next.  If the current running animation is stopped, no
+   * following animations will be started.
+   */
   sequence: sequenceImpl,
+  /**
+   * Starts an array of animations all at the same time.  By default, if one
+   * of the animations is stopped, they will all be stopped.  You can override
+   * this with the `stopTogether` flag.
+   */
   parallel: parallelImpl,
+  /**
+   * Array of animations may run in parallel (overlap), but are started in
+   * sequence with successive delays.  Nice for doing trailing effects.
+   */
   stagger: staggerImpl,
+  /**
+   * Loops a given animation continuously, so that each time it reaches the end,
+   * it resets and begins again from the start. Can specify number of times to
+   * loop using the key 'iterations' in the config. Will loop without blocking
+   * the UI thread if the child animation is set to 'useNativeDriver'.
+   */
   loop: loopImpl,
+  /**
+   *  Takes an array of mappings and extracts values from each arg accordingly,
+   *  then calls `setValue` on the mapped outputs.  e.g.
+   *
+   *```javascript
+   *  onScroll={Animated.event(
+   *    [{nativeEvent: {contentOffset: {x: this._scrollX}}}]
+   *    {listener},          // Optional async listener
+   *  )
+   *  ...
+   *  onPanResponderMove: Animated.event([
+   *    null,                // raw event arg ignored
+   *    {dx: this._panX},    // gestureState arg
+   *  ]),
+   *```
+   */
   event: eventImpl,
+  /**
+   * Make any React component Animatable.  Used to create `Animated.View`, etc.
+   */
   createAnimatedComponent,
   attachNativeEvent: attachNativeEventImpl,
   forkEvent: forkEventImpl,

packages/react-native/Libraries/BatchedBridge/NativeModules.js

@@ -180,6 +180,13 @@ function updateErrorWithErrorData(
   return Object.assign(error, errorData || {});
 }
 
+/**
+ * Native Modules written in ObjectiveC/Swift/Java exposed via the RCTBridge
+ * Define lazy getters for each module. These will return the module if already loaded, or load it if not.
+ * See https://reactnative.dev/docs/native-modules-ios
+ * @example
+ * const MyModule = NativeModules.ModuleName
+ */
 /* $FlowFixMe[unclear-type] unclear type of NativeModules */
 let NativeModules: {[moduleName: string]: any, ...} = {};
 if (global.nativeModuleProxy) {

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

@@ -9,6 +9,7 @@
  */
 
 'use strict';
+
 import type {HostInstance} from '../../../src/private/types/HostInstance';
 import type {ViewProps} from '../View/ViewPropTypes';
 
@@ -30,39 +31,75 @@ type IndicatorSize = number | 'small' | 'large';
 
 type ActivityIndicatorIOSProps = Readonly<{
   /**
-    Whether the indicator should hide when not animating.
-
-    @platform ios
-  */
+   * Whether the indicator should hide when not animating.
+   *
+   * @platform ios
+   */
   hidesWhenStopped?: ?boolean,
 }>;
+
 /** @build-types emit-as-interface Uniwind compatibility */
 export type ActivityIndicatorProps = Readonly<{
   ...ViewProps,
   ...ActivityIndicatorIOSProps,
 
   /**
-   	Whether to show the indicator (`true`) or hide it (`false`).
+   * Whether to show the indicator (`true`) or hide it (`false`).
    */
   animating?: ?boolean,
 
   /**
-    The foreground color of the spinner.
-
-    @default {@platform android} `null` (system accent default color)
-    @default {@platform ios} '#999999'
-  */
+   * The foreground color of the spinner.
+   *
+   * @default {@platform android} `null` (system accent default color)
+   * @default {@platform ios} '#999999'
+   */
   color?: ?ColorValue,
 
   /**
-    Size of the indicator.
-
-    @type enum(`'small'`, `'large'`)
-    @type {@platform android} number
-  */
+   * Size of the indicator.
+   *
+   * Small has a height of 20, large has a height of 36.
+   *
+   * @type enum(`'small'`, `'large'`)
+   * @type {@platform android} number
+   */
   size?: ?IndicatorSize,
 }>;
 
+/**
+ * Displays a circular loading indicator.
+ *
+ * Example:
+ *
+ * ```js
+ * import React from 'react';
+ * import {ActivityIndicator, StyleSheet, View} from 'react-native';
+ *
+ * const App = () => (
+ *   <View style={[styles.container, styles.horizontal]}>
+ *     <ActivityIndicator />
+ *     <ActivityIndicator size="large" />
+ *     <ActivityIndicator size="small" color="#0000ff" />
+ *     <ActivityIndicator size="large" color="#00ff00" />
+ *   </View>
+ * );
+ *
+ * const styles = StyleSheet.create({
+ *   container: {
+ *     flex: 1,
+ *     justifyContent: 'center',
+ *   },
+ *   horizontal: {
+ *     flexDirection: 'row',
+ *     justifyContent: 'space-around',
+ *     padding: 10,
+ *   },
+ * });
+ *
+ * export default App;
+ * ```
+ */
 const ActivityIndicator: component(
   ref?: React.RefSetter<ActivityIndicatorInstance>,
   ...props: ActivityIndicatorProps
@@ -129,38 +166,6 @@ const ActivityIndicator: component(
   );
 };
 
-/**
-  Displays a circular loading indicator.
-
-  ```SnackPlayer name=ActivityIndicator%20Example
-  import React from 'react';
-  import {ActivityIndicator, StyleSheet, View} from 'react-native';
-
-  const App = () => (
-    <View style={[styles.container, styles.horizontal]}>
-      <ActivityIndicator />
-      <ActivityIndicator size="large" />
-      <ActivityIndicator size="small" color="#0000ff" />
-      <ActivityIndicator size="large" color="#00ff00" />
-    </View>
-  );
-
-  const styles = StyleSheet.create({
-    container: {
-      flex: 1,
-      justifyContent: 'center',
-    },
-    horizontal: {
-      flexDirection: 'row',
-      justifyContent: 'space-around',
-      padding: 10,
-    },
-  });
-
-  export default App;
-```
-*/
-
 ActivityIndicator.displayName = 'ActivityIndicator';
 
 const styles = StyleSheet.create({