Migrate/audit JSDoc on public APIs (APIs) (#57383)

Summary:
Pull Request resolved: #57383

**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).

**Manual edits**

- `StyleSheet`

Commit 2 of 2 (APIs).

Replaces #57380.

Changelog:
[General][Added] - Strict TypeScript API: Component and API doc comment coverage has been significantly improved

___

Differential Revision: D110195868

fbshipit-source-id: 7d8880352c934702671f89a403f334e30b1e749c

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,
 }>;
@@ -50,9 +54,10 @@ export type ShareActionSheetError = Readonly<{
 }>;
 
 /**
- * Display action sheets and share sheets on iOS.
+ * Displays native iOS action sheets and share sheets.
  *
- * See https://reactnative.dev/docs/actionsheetios
+ * @see https://reactnative.dev/docs/actionsheetios
+ * @platform ios
  */
 const ActionSheetIOS = {
   /**
@@ -62,15 +67,13 @@ const ActionSheetIOS = {
    *
    * - `options` (array of strings) - a list of button titles (required)
    * - `cancelButtonIndex` (int) - index of cancel button in `options`
-   * - `destructiveButtonIndex` (int or array of ints) - index or indices of destructive buttons in `options`
+   * - `destructiveButtonIndex` (int or array of ints) - indices of destructive buttons in `options`
    * - `title` (string) - a title to show above the action sheet
    * - `message` (string) - a message to show below the title
    * - `disabledButtonIndices` (array of numbers) - a list of button indices which should be disabled
    *
-   * The 'callback' function takes one parameter, the zero-based index
-   * of the selected item.
-   *
-   * See https://reactnative.dev/docs/actionsheetios#showactionsheetwithoptions
+   * The `callback` function receives the zero-based index of the selected
+   * item.
    */
   showActionSheetWithOptions(
     options: ActionSheetIOSOptions,
@@ -136,27 +139,19 @@ const ActionSheetIOS = {
   },
 
   /**
-   * Display the iOS share sheet. The `options` object should contain
-   * one or both of `message` and `url` and can additionally have
-   * a `subject` or `excludedActivityTypes`:
+   * Display the iOS share sheet. The `options` object should contain one or
+   * both of `message` and `url` and can additionally have a `subject` or
+   * `excludedActivityTypes`:
    *
    * - `url` (string) - a URL to share
    * - `message` (string) - a message to share
    * - `subject` (string) - a subject for the message
-   * - `excludedActivityTypes` (array) - the activities to exclude from
-   *   the ActionSheet
+   * - `excludedActivityTypes` (array) - the activities to exclude from the ActionSheet
    * - `tintColor` (color) - tint color of the buttons
    *
-   * The 'failureCallback' function takes one parameter, an error object.
-   * The only property defined on this object is an optional `stack` property
-   * of type `string`.
-   *
-   * The 'successCallback' function takes two parameters:
-   *
-   * - a boolean value signifying success or failure
-   * - a string that, in the case of success, indicates the method of sharing
-   *
-   * See https://reactnative.dev/docs/actionsheetios#showshareactionsheetwithoptions
+   * The `failureCallback` function receives an error object. The
+   * `successCallback` function receives a boolean indicating success and a
+   * string describing the sharing method used.
    */
   showShareActionSheetWithOptions(
     options: ShareActionSheetIOSOptions,
@@ -186,8 +181,8 @@ const ActionSheetIOS = {
   },
 
   /**
-   * Dismisses the most upper iOS action sheet presented, if no action sheet is
-   * present a warning is displayed.
+   * Dismiss the most upper action sheet currently presented. Displays a
+   * warning if no action sheet is present.
    */
   dismissActionSheet: () => {
     invariant(RCTActionSheetManager, "ActionSheetManager doesn't exist");

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

@@ -57,9 +57,43 @@ export type AlertOptions = {
  * alerts. On iOS, you can show an alert that prompts the user to enter
  * some information.
  *
- * See https://reactnative.dev/docs/alert
+ * ## 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')
+ *
+ * Example:
+ *
+ * ```tsx
+ * // 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 {
+  /**
+   * Display an alert dialog with the specified title, message, and buttons.
+   * On Android, at most three buttons can be specified. On iOS, any number of
+   * buttons can be used.
+   */
   static alert(
     title: ?string,
     message?: ?string,
@@ -140,6 +174,9 @@ class Alert {
   }
 
   /**
+   * Create and display a prompt to enter text. Accepts a title, message,
+   * callback or buttons, input type, default value, keyboard type, and options.
+   *
    * @platform ios
    */
   static prompt(

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/Animated/Easing.js

@@ -15,9 +15,8 @@ let ease;
 export type EasingFunction = (t: number) => number;
 
 /**
- * The `Easing` module implements common easing functions. This module is used
- * by [Animate.timing()](docs/animate.html#timing) to convey physically
- * believable motion in animations.
+ * Implements common easing functions for use with `Animated.timing()` to convey
+ * physically believable motion in animations.
  *
  * You can find a visualization of some common easing functions at
  * http://easings.net/
@@ -58,6 +57,8 @@ export type EasingFunction = (t: number) => number;
  * - [`in`](docs/easing.html#in) runs an easing function forwards
  * - [`inOut`](docs/easing.html#inout) makes any easing function symmetrical
  * - [`out`](docs/easing.html#out) runs an easing function backwards
+ *
+ * @see https://reactnative.dev/docs/easing
  */
 const EasingStatic = {
   /**