Add TSDoc to public API (#5377)

This PR aims to cover the entirety of Reanimated public API with short,
descriptive TSDoc comments. This will allow developers to stay longer in
their editors and save some time searching and googling.

Under each function there's a link to the documentation.

.eslintrc.js

@@ -12,7 +12,14 @@ module.exports = {
     'plugin:import/typescript',
     'plugin:react-hooks/recommended',
   ],
-  plugins: ['react', 'react-native', 'import', 'jest', '@typescript-eslint'],
+  plugins: [
+    'react',
+    'react-native',
+    'import',
+    'jest',
+    '@typescript-eslint',
+    'eslint-plugin-tsdoc',
+  ],
   env: {
     'react-native/react-native': true,
     'jest/globals': true,
@@ -52,5 +59,6 @@ module.exports = {
       'error',
       { fixMixedExportsWithInlineTypeSpecifier: false },
     ],
+    'tsdoc/syntax': 'error',
   },
 };

docs/docs/advanced/setNativeProps.mdx

@@ -10,7 +10,7 @@ sidebar_position: 7
 
 `setNativeProps` is an escape hatch for specific edge-cases.
 
-You should always reach for [`useAnimatedStyle`](docs/core/useAnimatedStyle) and [`useAnimatedProps`](docs/core/useAnimatedProps) first when animating styles or properties.
+You should always reach for [`useAnimatedStyle`](/docs/core/useAnimatedStyle) and [`useAnimatedProps`](/docs/core/useAnimatedProps) first when animating styles or properties.
 
 :::
 
@@ -48,7 +48,7 @@ function setNativeProps<T extends Component>(
 
 #### `animatedRef`
 
-An [animated ref](/docs/core/useAnimatedRef#returns) connected to the component you'd want to get the measurements from. The animated ref has to be passed either to an [Animated component](/docs/fundamentals/glossary#animated-component) or a React Native built-in component.
+An [animated ref](/docs/core/useAnimatedRef#returns) connected to the component you'd want to update. The animated ref has to be passed either to an [Animated component](/docs/fundamentals/glossary#animated-component) or a React Native built-in component.
 
 #### `updates`
 

docs/docs/animations/withDecay.mdx

@@ -4,7 +4,7 @@ sidebar_position: 3
 
 # withDecay
 
-`withDecay` lets you create animations that mimic objects in motion. The animation will start with the provided velocity and slow down over time according to the given deceleration rate until it stops.
+`withDecay` lets you create animations that mimic objects in motion with friction. The animation will start with the provided velocity and slow down over time according to the given deceleration rate until it stops.
 
 import DecayBasic from '@site/src/examples/DecayBasic';
 import DecayBasicSrc from '!!raw-loader!@site/src/examples/DecayBasic';
@@ -80,7 +80,7 @@ A function called on animation complete. In case the animation is cancelled, the
 
 ### Returns
 
-`withDecay` returns an [animation object](/docs/fundamentals/glossary#animation-object). It can be either assigned directly to a [shared value](/docs/fundamentals/glossary#shared-value) or can be used as a value for a style object returned from [useAnimatedStyle](/docs/core/useAnimatedStyle).
+`withDecay` returns an [animation object](/docs/fundamentals/glossary#animation-object) which holds the current state of the animation. It can be either assigned directly to a [shared value](/docs/fundamentals/glossary#shared-value) or can be used as a value for a style object returned from [useAnimatedStyle](/docs/core/useAnimatedStyle).
 
 ## Example
 

docs/docs/animations/withDelay.mdx

@@ -54,7 +54,7 @@ A parameter that determines how the animation responds to the device's reduced m
 
 ### Returns
 
-`withDelay` returns an [animation object](/docs/fundamentals/glossary#animation-object). It can be either assigned directly to a [shared value](/docs/fundamentals/glossary#shared-value) or can be used as a value for a style object returned from [useAnimatedStyle](docs/core/useAnimatedStyle).
+`withDelay` returns an [animation object](/docs/fundamentals/glossary#animation-object) which holds the current state of the animation. It can be either assigned directly to a [shared value](/docs/fundamentals/glossary#shared-value) or can be used as a value for a style object returned from [useAnimatedStyle](docs/core/useAnimatedStyle).
 
 ## Example
 

docs/docs/animations/withRepeat.mdx

@@ -49,7 +49,7 @@ enum ReduceMotion {
 
 #### `animation`
 
-The animation you want to repeat.
+An [animation object](/docs/fundamentals/glossary#animation-object) you want to repeat.
 
 #### `numberOfReps` <Optional />
 
@@ -73,7 +73,7 @@ A parameter that determines how the animation responds to the device's reduced m
 
 ### Returns
 
-`withRepeat` returns an [animation object](/docs/fundamentals/glossary#animation-object). It can be either assigned directly to a [shared value](/docs/fundamentals/glossary#shared-value) or can be used as a value for a style object returned from [useAnimatedStyle](docs/core/useAnimatedStyle).
+`withRepeat` returns an [animation object](/docs/fundamentals/glossary#animation-object) which holds the current state of the animation. It can be either assigned directly to a [shared value](/docs/fundamentals/glossary#shared-value) or can be used as a value for a style object returned from [useAnimatedStyle](docs/core/useAnimatedStyle).
 
 ## Example
 

docs/docs/animations/withSequence.mdx

@@ -54,7 +54,7 @@ Any number of [animation objects](docs/fundamentals/glossary#animation-object) t
 
 ### Returns
 
-`withSequence` returns an [animation object](/docs/fundamentals/glossary#animation-object). It can be either assigned directly to a [shared value](/docs/fundamentals/glossary#shared-value) or can be used as a value for a style object returned from [useAnimatedStyle](docs/core/useAnimatedStyle).
+`withSequence` returns an [animation object](/docs/fundamentals/glossary#animation-object) which holds the current state of the animation. It can be either assigned directly to a [shared value](/docs/fundamentals/glossary#shared-value) or can be used as a value for a style object returned from [useAnimatedStyle](docs/core/useAnimatedStyle).
 
 ## Example
 

docs/docs/animations/withSpring.mdx

@@ -81,7 +81,7 @@ Available properties:
 | overshootClamping         | `boolean`      | false                 | Whether a spring can bounce over the `toValue`.                                                                           |
 | restDisplacementThreshold | `number`       | 0.01                  | The displacement below which the spring will snap to `toValue` without further oscillations.                              |
 | restSpeedThreshold        | `number`       | 2                     | The speed in pixels per second from which the spring will snap to `toValue` without further oscillations.                 |
-| reduceMotion <Optional /> | `ReduceMotion` | `ReduceMotion.System` | A parameter that determines how the animation responds to the device's reduced motion accessibility setting.              |
+| reduceMotion              | `ReduceMotion` | `ReduceMotion.System` | A parameter that determines how the animation responds to the device's reduced motion accessibility setting.              |
 
 :::info
 The `mass` and `damping` (physics-based) properties can't be used at the same time as `duration` and `dampingRatio` (duration-based).
@@ -95,7 +95,7 @@ A function called upon animation completion. If the animation is cancelled, the
 
 ### Returns
 
-`withSpring` returns an [animation object](/docs/fundamentals/glossary#animation-object). It can be either assigned directly to a [shared value](/docs/fundamentals/glossary#shared-value) or can be used as a value for a style object returned from [useAnimatedStyle](docs/core/useAnimatedStyle).
+`withSpring` returns an [animation object](/docs/fundamentals/glossary#animation-object) which holds the current state of the animation. It can be either assigned directly to a [shared value](/docs/fundamentals/glossary#shared-value) or can be used as a value for a style object returned from [useAnimatedStyle](docs/core/useAnimatedStyle).
 
 ## Example
 

docs/docs/animations/withTiming.mdx

@@ -65,11 +65,11 @@ import { useTimingPlayground } from '@site/src/components/InteractivePlayground'
 
 Available properties:
 
-| Name                      | Type           | Default                     | Description                                                                                                  |
-| ------------------------- | -------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------ |
-| duration <Optional />     | `number`       | 300                         | Length of the animation (in milliseconds).                                                                   |
-| easing <Optional />       | `Easing`       | `Easing.inOut(Easing.quad)` | An easing function which defines the animation curve.                                                        |
-| reduceMotion <Optional /> | `ReduceMotion` | `ReduceMotion.System`       | A parameter that determines how the animation responds to the device's reduced motion accessibility setting. |
+| Name         | Type           | Default                     | Description                                                                                                  |
+| ------------ | -------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| duration     | `number`       | 300                         | Length of the animation (in milliseconds).                                                                   |
+| easing       | `Easing`       | `Easing.inOut(Easing.quad)` | An easing function which defines the animation curve.                                                        |
+| reduceMotion | `ReduceMotion` | `ReduceMotion.System`       | A parameter that determines how the animation responds to the device's reduced motion accessibility setting. |
 
 ##### `Easing`
 
@@ -124,7 +124,7 @@ A function called upon animation completion. If the animation is cancelled, the
 
 ### Returns
 
-`withTiming` returns an [animation object](/docs/fundamentals/glossary#animation-object). It can be either assigned directly to a [shared value](/docs/fundamentals/glossary#shared-value) or can be used as a value for a style object returned from [useAnimatedStyle](docs/core/useAnimatedStyle).
+`withTiming` returns an [animation object](/docs/fundamentals/glossary#animation-object) which holds the current state of the animation. It can be either assigned directly to a [shared value](/docs/fundamentals/glossary#shared-value) or can be used as a value for a style object returned from [useAnimatedStyle](docs/core/useAnimatedStyle).
 
 ## Example
 

docs/docs/core/useAnimatedRef.mdx

@@ -6,7 +6,7 @@ sidebar_position: 4
 
 `useAnimatedRef` lets you get a reference of a view. Used alongside [`measure`](/docs/advanced/measure), [`scrollTo`](/docs/scroll/scrollTo), and [`useScrollViewOffset`](/docs/scroll/useScrollViewOffset) functions.
 
-An object defined using `useAnimatedRef` has to be passed to the `ref` property of a component.
+You need to pass the object defined using `useAnimatedRef` to the `ref` property of a component.
 
 ## Reference
 

docs/docs/fundamentals/glossary.mdx

@@ -33,7 +33,7 @@ const AnimatedCircle = Animated.createAnimatedComponent(Circle);
 
 Shared values are a driving factor of all your animations in Reanimated.
 
-They are defined using `useSharedValue` hook:
+They are defined using [`useSharedValue`](/docs/core/useSharedValue) hook:
 
 ```javascript
 import { useSharedValue } from 'react-native-reanimated';
@@ -111,6 +111,24 @@ function App() {
 }
 ```
 
+## Layout animation modifier
+
+Layout animation modifiers are methods used to customize layout animations.
+
+```jsx
+<Animated.View entering={FadeOutLeft.duration(500).easing(Easing.ease)} />
+```
+
+Reanimated comes with plenty of built-in layout animation modifiers. Some of them are:
+
+- `.duration(durationMs: number)` - the length of the animation (in milliseconds).
+- `.easing(easingFunction: EasingFunction)` - an easing function which defines the animation curve.
+- `.springify()` - enables the spring-based animation configuration.
+- `.damping(value: number)` - decides how quickly a spring stops moving.
+- `.withCallback(callback: (finished: boolean) => void)` - the callback that will fire after the animation ends.
+
+For a list of all available modifiers for each animation refer to the documentation of individual layout animation.
+
 ## Worklet
 
 Worklets are short-running JavaScript functions that can be run on the [UI thread](/docs/fundamentals/glossary#ui-thread). They can also be run on a JavaScript thread just as you would run a function in your code.

docs/docs/layout-animations/layout-animation-config.mdx

@@ -78,7 +78,7 @@ import LayoutAnimationConfigSrc from '!!raw-loader!@site/src/examples/LayoutAnim
 
 ## Platform compatibility
 
-<div className="compatibility">
+<div className="platform-compatibility">
 
 | Android | iOS | Web |
 | ------- | --- | --- |

docs/docs/layout-animations/layout-transitions.mdx

@@ -43,7 +43,7 @@ Below we listed all of the currently available predefined layout transitions. Ea
 
 If you cannot find an transition that suits you then you can create a custom one. If you think that the animation should be here, please open an issue or create a pull request.
 
-### Layout
+### Linear transition
 
 Linear transition, animates both position and dimension in the same way.
 

package.json

@@ -149,6 +149,7 @@
     "eslint-plugin-promise": "^6.0.0",
     "eslint-plugin-react-hooks": "^4.6.0",
     "eslint-plugin-standard": "^5.0.0",
+    "eslint-plugin-tsdoc": "^0.2.17",
     "husky": "^7.0.4",
     "jest": "^29.0.0",
     "lint-staged": "^11.2.0",

src/createAnimatedComponent/createAnimatedComponent.tsx

@@ -77,6 +77,13 @@ type Options<P> = {
   setNativeProps: (ref: AnimatedComponentRef, props: P) => void;
 };
 
+/**
+ * Lets you create an Animated version of any React Native component.
+ *
+ * @param component - The component you want to make animatable.
+ * @returns A component that Reanimated is capable of animating.
+ * @see https://docs.swmansion.com/react-native-reanimated/docs/core/createAnimatedComponent
+ */
 export function createAnimatedComponent<P extends object>(
   component: FunctionComponent<P>,
   options?: Options<P>

src/createAnimatedComponent/setAndForwardRef.ts

@@ -5,6 +5,7 @@
 
 import type { MutableRefObject } from 'react';
 
+/* eslint-disable */
 /**
  * This is a helper function for when a component needs to be able to forward a ref
  * to a child component, but still needs to have access to that component as part of
@@ -35,6 +36,7 @@ import type { MutableRefObject } from 'react';
  *
  *   module.exports = MyViewWithRef;
  */
+/* eslint-enable */
 
 type ForwardedRef<T> = () => MutableRefObject<T> | ((ref: T) => void);
 

src/reanimated2/Easing.ts

@@ -50,14 +50,14 @@ import { Bezier } from './Bezier';
 export type EasingFunction = (t: number) => number;
 
 /**
- * @deprecated Please use `EasingFunction` type instead.
+ * @deprecated Please use {@link EasingFunction} type instead.
  */
 export type EasingFn = EasingFunction;
 
 export type EasingFunctionFactory = { factory: () => EasingFunction };
 
 /**
- * @deprecated Please use `EasingFunctionFactory` type instead.
+ * @deprecated Please use {@link EasingFunctionFactory} type instead.
  */
 export type EasingFactoryFn = EasingFunctionFactory;
 /**
@@ -153,7 +153,7 @@ function exp(t: number): number {
  * forth.
  *
  * Default bounciness is 1, which overshoots a little bit once. 0 bounciness
- * doesn't overshoot at all, and bounciness of N > 1 will overshoot about N
+ * doesn't overshoot at all, and bounciness of N \> 1 will overshoot about N
  * times.
  *
  * http://easings.net/#easeInElastic

src/reanimated2/animation/decay/decay.ts

@@ -49,6 +49,14 @@ function validateConfig(config: DefaultDecayConfig): void {
   }
 }
 
+/**
+ * Lets you create animations that mimic objects in motion with friction.
+ *
+ * @param config - The decay animation configuration - {@link DecayConfig}.
+ * @param callback - A function called upon animation completion - {@link AnimationCallback}.
+ * @returns An [animation object](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/glossary#animation-object) which holds the current state of the animation.
+ * @see https://docs.swmansion.com/react-native-reanimated/docs/animations/withDecay
+ */
 export const withDecay = function (
   userConfig: DecayConfig,
   callback?: AnimationCallback

src/reanimated2/animation/decay/utils.ts

@@ -28,6 +28,18 @@ export interface InnerDecayAnimation
   springActive?: boolean;
 }
 
+/**
+ * The decay animation configuration.
+ *
+ * @param velocity - Initial velocity of the animation. Defaults to 0.
+ * @param deceleration - The rate at which the velocity decreases over time. Defaults to 0.998.
+ * @param clamp - Array of two numbers which restricts animation's range. Defaults to [].
+ * @param velocityFactor - Velocity multiplier. Defaults to 1.
+ * @param rubberBandEffect - Makes the animation bounce over the limit specified in `clamp`. Defaults to `false`.
+ * @param rubberBandFactor - Strength of the rubber band effect. Defaults to 0.6.
+ * @param reduceMotion - Determines how the animation responds to the device's reduced motion accessibility setting. Default to `ReduceMotion.System` - {@link ReduceMotion}.
+ * @see https://docs.swmansion.com/react-native-reanimated/docs/animations/withDecay#config
+ */
 export type DecayConfig = {
   deceleration?: number;
   velocityFactor?: number;

src/reanimated2/animation/delay.ts

@@ -16,6 +16,15 @@ type withDelayType = <T extends AnimatableValue>(
   reduceMotion?: ReduceMotion
 ) => T;
 
+/**
+ * An animation modifier that lets you start an animation with a delay.
+ *
+ * @param delayMs - Duration (in milliseconds) before the animation starts.
+ * @param nextAnimation - The animation to delay.
+ * @param reduceMotion - Determines how the animation responds to the device's reduced motion accessibility setting. Default to `ReduceMotion.System` - {@link ReduceMotion}.
+ * @returns An [animation object](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/glossary#animation-object) which holds the current state of the animation.
+ * @see https://docs.swmansion.com/react-native-reanimated/docs/animations/withDelay
+ */
 export const withDelay = function <T extends AnimationObject>(
   delayMs: number,
   _nextAnimation: T | (() => T),

src/reanimated2/animation/repeat.ts

@@ -19,6 +19,17 @@ type withRepeatType = <T extends AnimatableValue>(
   reduceMotion?: ReduceMotion
 ) => T;
 
+/**
+ * Lets you repeat an animation given number of times or run it indefinitely.
+ *
+ * @param animation - An animation object you want to repeat.
+ * @param numberOfReps - The number of times the animation is going to be repeated. Defaults to 2.
+ * @param reverse - Whether the animation should run in reverse every other repetition. Defaults to false.
+ * @param callback - A function called on animation complete.
+ * @param reduceMotion - Determines how the animation responds to the device's reduced motion accessibility setting. Default to `ReduceMotion.System` - {@link ReduceMotion}.
+ * @returns An [animation object](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/glossary#animation-object) which holds the current state of the animation.
+ * @see https://docs.swmansion.com/react-native-reanimated/docs/animations/withRepeat
+ */
 export const withRepeat = function <T extends AnimationObject>(
   _nextAnimation: T | (() => T),
   numberOfReps = 2,

src/reanimated2/animation/sequence.ts

@@ -9,6 +9,14 @@ import type {
   Timestamp,
 } from '../commonTypes';
 
+/**
+ * Lets you run animations in a sequence.
+ *
+ * @param reduceMotion - Determines how the animation responds to the device's reduced motion accessibility setting. Default to `ReduceMotion.System` - {@link ReduceMotion}.
+ * @param animations - Any number of animation objects to be run in a sequence.
+ * @returns An [animation object](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/glossary#animation-object) which holds the current state of the animation/
+ * @see https://docs.swmansion.com/react-native-reanimated/docs/animations/withSequence
+ */
 export function withSequence<T extends AnimatableValue>(
   _reduceMotion: ReduceMotion,
   ...animations: T[]

src/reanimated2/animation/spring.ts

@@ -29,6 +29,15 @@ type withSpringType = <T extends AnimatableValue>(
   callback?: AnimationCallback
 ) => T;
 
+/**
+ * Lets you create spring-based animations.
+ *
+ * @param toValue - the value at which the animation will come to rest - {@link AnimatableValue}
+ * @param config - the spring animation configuration - {@link SpringConfig}
+ * @param callback - a function called on animation complete - {@link AnimationCallback}
+ * @returns an [animation object](https://docs.swmansion.com/react-native-reanimated/docs/fundamentals/glossary#animation-object) which holds the current state of the animation
+ * @see https://docs.swmansion.com/react-native-reanimated/docs/animations/withSpring
+ */
 export const withSpring = ((
   toValue: AnimatableValue,
   userConfig?: SpringConfig,