From 940d648955ec4af4173689564a7ec8543b71fdf6 Mon Sep 17 00:00:00 2001 From: Alex Hunt Date: Tue, 30 Jun 2026 06:48:34 -0700 Subject: [PATCH] Improve generated API doc comments (match baseline) (#57380) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Summary: Pull Request resolved: https://github.com/react/react-native/pull/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 --- .../ActionSheetIOS/ActionSheetIOS.js | 4 + .../react-native/Libraries/Alert/Alert.js | 27 ++ .../Libraries/Animated/AnimatedExports.js | 22 ++ .../Animated/AnimatedImplementation.js | 104 ++++++ .../Libraries/BatchedBridge/NativeModules.js | 7 + .../ActivityIndicator/ActivityIndicator.js | 99 +++--- .../Libraries/Components/Button.js | 333 +++++++++--------- .../Components/Clipboard/Clipboard.js | 5 + .../Libraries/Components/Keyboard/Keyboard.js | 89 ++--- .../Components/Pressable/Pressable.js | 2 + .../ProgressBarAndroidTypes.js | 17 + .../Components/ScrollView/ScrollView.js | 31 ++ .../TextInput/InputAccessoryView.js | 25 +- .../Components/TextInput/TextInput.flow.js | 9 + .../Components/TextInput/TextInput.js | 222 ++++++------ .../Components/Touchable/Touchable.js | 169 +++++---- .../Touchable/TouchableHighlight.js | 194 +++++----- .../Components/Touchable/TouchableOpacity.js | 2 + .../Components/View/ViewAccessibility.js | 21 +- .../Components/View/ViewPropTypes.js | 11 + .../EventEmitter/NativeEventEmitter.js | 29 ++ .../EventEmitter/RCTNativeAppEventEmitter.js | 3 + .../Libraries/Image/ImageProps.js | 14 +- .../Libraries/Interaction/PanResponder.js | 189 +++++----- .../react-native/Libraries/Linking/Linking.js | 14 +- .../Libraries/Lists/SectionList.js | 3 + .../react-native/Libraries/LogBox/LogBox.js | 6 +- .../react-native/Libraries/Modal/Modal.js | 11 +- .../PermissionsAndroid/PermissionsAndroid.js | 22 +- .../PushNotificationIOS.js | 4 + .../Libraries/ReactNative/AppRegistry.js | 14 +- .../Libraries/ReactNative/UIManager.js | 53 +++ .../PlatformColorValueTypes.js.flow | 6 + .../Libraries/StyleSheet/StyleSheetTypes.js | 20 ++ .../Libraries/Types/CoreEventTypes.js | 3 + .../Libraries/Utilities/BackHandler.js.flow | 16 + .../Libraries/Vibration/Vibration.js | 11 +- 37 files changed, 1124 insertions(+), 687 deletions(-) diff --git a/packages/react-native/Libraries/ActionSheetIOS/ActionSheetIOS.js b/packages/react-native/Libraries/ActionSheetIOS/ActionSheetIOS.js index 78b6cda1bf11..5b0b17b51f48 100644 --- a/packages/react-native/Libraries/ActionSheetIOS/ActionSheetIOS.js +++ b/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, userInterfaceStyle?: ?string, }>; diff --git a/packages/react-native/Libraries/Alert/Alert.js b/packages/react-native/Libraries/Alert/Alert.js index df9908ebd15b..d0f9f6f5ecc3 100644 --- a/packages/react-native/Libraries/Alert/Alert.js +++ b/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 { diff --git a/packages/react-native/Libraries/Animated/AnimatedExports.js b/packages/react-native/Libraries/Animated/AnimatedExports.js index d767e8a15bc7..55940d81c39e 100644 --- a/packages/react-native/Libraries/Animated/AnimatedExports.js +++ b/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 { 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 { 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; }, diff --git a/packages/react-native/Libraries/Animated/AnimatedImplementation.js b/packages/react-native/Libraries/Animated/AnimatedImplementation.js index d14425499cab..4a9d76a4806a 100644 --- a/packages/react-native/Libraries/Animated/AnimatedImplementation.js +++ b/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, diff --git a/packages/react-native/Libraries/BatchedBridge/NativeModules.js b/packages/react-native/Libraries/BatchedBridge/NativeModules.js index c38eab148e98..3e16553e26d1 100644 --- a/packages/react-native/Libraries/BatchedBridge/NativeModules.js +++ b/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) { diff --git a/packages/react-native/Libraries/Components/ActivityIndicator/ActivityIndicator.js b/packages/react-native/Libraries/Components/ActivityIndicator/ActivityIndicator.js index 63bddf2e9504..895c7409cfdf 100644 --- a/packages/react-native/Libraries/Components/ActivityIndicator/ActivityIndicator.js +++ b/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 = () => ( + * + * + * + * + * + * + * ); + * + * 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, ...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 = () => ( - - - - - - - ); - - 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({ diff --git a/packages/react-native/Libraries/Components/Button.js b/packages/react-native/Libraries/Components/Button.js index 8ed215d6a6cb..26c9da4f6835 100644 --- a/packages/react-native/Libraries/Components/Button.js +++ b/packages/react-native/Libraries/Components/Button.js @@ -30,101 +30,101 @@ 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 to be called when the user taps the button. The first function + * argument is an event in form of [GestureResponderEvent](pressevent). */ 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, /** @@ -133,14 +133,14 @@ export type ButtonProps = Readonly<{ */ '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. + * Used to locate this view in end-to-end tests. */ testID?: ?string, @@ -171,114 +171,6 @@ export type ButtonProps = Readonly<{ 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 -