chore: Enable TSDoc and JSDoc formatting

.eslintrc.js

@@ -57,7 +57,7 @@ module.exports = {
     'import',
     'jest',
     '@typescript-eslint',
-    'eslint-plugin-tsdoc',
+    'tsdoc',
   ],
   env: {
     'react-native/react-native': true,

apps/common-app/src/types.ts

@@ -2,12 +2,13 @@
 import React from 'react';
 
 /**
- * We need to augment react types because rn for web provides non-standard way of measuring components by injecting `measure` method to the ref.
+ * We need to augment react types because rn for web provides non-standard way
+ * of measuring components by injecting `measure` method to the ref.
  *
  * Reference:
  * https://github.com/necolas/react-native-web/blob/c47bec7b93d6a3b7c31bbc8bb2e4acd117b79bfc/packages/react-native-web/src/modules/usePlatformMethods/index.js#L69
  * https://github.com/necolas/react-native-web/blob/c47bec7b93d6a3b7c31bbc8bb2e4acd117b79bfc/packages/react-native-web/src/exports/UIManager/index.js#L63
- *  */
+ */
 
 declare module 'react' {
   interface Component {

package.json

@@ -21,6 +21,7 @@
     "husky": "^9.0.11",
     "lint-staged": "^15.2.2",
     "prettier": "^3.3.3",
+    "prettier-plugin-jsdoc": "^1.3.0",
     "typescript": "~5.3.0"
   }
 }

packages/react-native-reanimated/.eslintrc.js

@@ -1,8 +1,13 @@
 module.exports = {
   extends: ['../../.eslintrc.js'],
-  plugins: ['eslint-plugin-reanimated'],
+  overrides: [
+    {
+      files: ['./src/**/*.ts', './src/**/*.tsx'],
+      plugins: ['reanimated'],
+      rules: {
+        'reanimated/use-reanimated-error': 'error',
+      },
+    },
+  ],
   ignorePatterns: ['lib'],
-  rules: {
-    'reanimated/use-reanimated-error': 'error',
-  },
 };

packages/react-native-reanimated/plugin/src/autoworkletization.ts

@@ -58,10 +58,7 @@ const functionArgsToWorkletize = new Map([
   ['executeOnUIRuntimeSync', [0]],
 ]);
 
-/**
- *
- * @returns `true` if the function was workletized, `false` otherwise.
- */
+/** @returns `true` if the function was workletized, `false` otherwise. */
 export function processIfAutoworkletizableCallback(
   path: NodePath<WorkletizableFunction>,
   state: ReanimatedPluginPass

packages/react-native-reanimated/plugin/src/class.ts

@@ -124,10 +124,13 @@ function appendWorkletDirectiveToPolyfills(statements: Statement[]) {
 
 /**
  * Replaces
+ *
  * ```ts
  * const Clazz = ...;
  * ```
- * with
+ *
+ * With
+ *
  * ```ts
  * const Clazz__classFactory = ...;
  * const Clazz = Clazz__classFactory();
@@ -312,8 +315,8 @@ function recursiveTopoSort(
 }
 
 /**
- * Checks if an identifier is a reference to an outside dependency.
- * The condition was made by trial and error.
+ * Checks if an identifier is a reference to an outside dependency. The
+ * condition was made by trial and error.
  */
 function isOutsideDependency(
   identifierPath: NodePath<Identifier>,

packages/react-native-reanimated/plugin/src/file.ts

@@ -55,9 +55,7 @@ export function processIfWorkletFile(
   return true;
 }
 
-/**
- * Adds a worklet directive to each viable top-level entity in the file.
- */
+/** Adds a worklet directive to each viable top-level entity in the file. */
 function processWorkletFile(programPath: NodePath<Program>) {
   const statements = programPath.get('body');
   dehoistCommonJSExports(programPath.node);
@@ -126,7 +124,8 @@ function processWorkletAggregator(objectPath: NodePath<ObjectExpression>) {
  *
  * `() => 1` becomes `() => { return 1 }`
  *
- * This is necessary because the worklet directive is only allowed on block statements.
+ * This is necessary because the worklet directive is only allowed on block
+ * statements.
  */
 function replaceImplicitReturnWithBlock(path: ArrowFunctionExpression) {
   if (!isBlockStatement(path.body)) {

packages/react-native-reanimated/plugin/src/globals.ts

@@ -121,11 +121,11 @@ const notCapturedIdentifiers = [
 ];
 
 /**
- * @deprecated Since we moved on to using `global.` prefix in Reanimated, we don't need to
- * capture these identifiers anymore. However, for safety reasons and 3rd party libraries,
- * we still keep them in the list.
+ * @deprecated Since we moved on to using `global.` prefix in Reanimated, we
+ *   don't need to capture these identifiers anymore. However, for safety
+ *   reasons and 3rd party libraries, we still keep them in the list.
  *
- * `_WORKLET` is the only exception since it's a part of the public API.
+ *   `_WORKLET` is the only exception since it's a part of the public API.
  */
 // eslint-disable-next-line camelcase
 const notCapturedIdentifiers_DEPRECATED = [

packages/react-native-reanimated/plugin/src/utils.ts

@@ -19,10 +19,16 @@ export function isRelease() {
 }
 
 /**
- * This function allows to add custom globals such as host-functions.
- * Those globals have to be passed as an argument for the plugin in babel.config.js.
+ * This function allows to add custom globals such as host-functions. Those
+ * globals have to be passed as an argument for the plugin in babel.config.js.
  *
- * For example: `plugins: [['react-native-reanimated/plugin', { globals: ['myHostFunction'] }]]`
+ * For example:
+ *
+ * ```js
+ * plugins: [
+ *   ['react-native-reanimated/plugin', { globals: ['myHostFunction'] }],
+ * ];
+ * ```
  */
 export function addCustomGlobals(this: ReanimatedPluginPass) {
   if (this.opts && Array.isArray(this.opts.globals)) {
@@ -33,34 +39,38 @@ export function addCustomGlobals(this: ReanimatedPluginPass) {
 }
 
 /**
- * This function replaces the node with a factory call while making
- * sure that it's a legal operation.
- * If the node cannot be simply replaced with a factory call, it will
- * be replaced with a variable declaration.
+ * This function replaces the node with a factory call while making sure that
+ * it's a legal operation. If the node cannot be simply replaced with a factory
+ * call, it will be replaced with a variable declaration.
  *
  * For example:
+ *
  * ```ts
- *  const foo = function() {
- *    'worklet';
- *    return 1;
- *  };
+ * const foo = function () {
+ *   'worklet';
+ *   return 1;
+ * };
  * ```
- * becomes
+ *
+ * Becomes
+ *
  * ```ts
- *  const foo = factoryCall();
+ * const foo = factoryCall();
  * ```
+ *
  * But:
- * ```
- *   export function foo() {
- *     'worklet';
- *     return 1;
- *   };
+ *
+ * ```ts
+ * export function foo() {
+ *   'worklet';
+ *   return 1;
+ * }
  * ```
  *
- * becomes
+ * Becomes
  *
  * ```ts
- *   export const foo = factoryCall();
+ * export const foo = factoryCall();
  * ```
  */
 export function replaceWithFactoryCall(

packages/react-native-reanimated/plugin/src/workletStringCode.ts

@@ -161,7 +161,8 @@ export function buildWorkletString(
 }
 
 /**
- * Function that restores recursive calls after the name of the worklet has changed.
+ * Function that restores recursive calls after the name of the worklet has
+ * changed.
  */
 function restoreRecursiveCalls(file: BabelFile, newName: string): void {
   traverse(file, {

packages/react-native-reanimated/plugin/src/workletSubstitution.ts

@@ -10,10 +10,7 @@ import { WorkletizableFunction } from './types';
 import { replaceWithFactoryCall } from './utils';
 import { makeWorkletFactoryCall } from './workletFactoryCall';
 
-/**
- *
- * @returns `true` if the function was workletized, `false` otherwise.
- */
+/** @returns `true` if the function was workletized, `false` otherwise. */
 export function processIfWithWorkletDirective(
   path: NodePath<WorkletizableFunction>,
   state: ReanimatedPluginPass
@@ -33,12 +30,13 @@ export function processIfWithWorkletDirective(
 
 /**
  * Replaces
+ *
  * - `FunctionDeclaration`,
  * - `FunctionExpression`,
  * - `ArrowFunctionExpression`
  * - `ObjectMethod`
  *
- * with a workletized version of itself.
+ * With a workletized version of itself.
  */
 export function processWorklet(
   path: NodePath<WorkletizableFunction>,

packages/react-native-reanimated/src/Animated.ts

@@ -29,55 +29,68 @@ export {
   addWhitelistedUIProps,
 } from './ConfigHelper';
 /**
- * @deprecated Please import `Extrapolate` directly from `react-native-reanimated` instead of `Animated` namespace.
+ * @deprecated Please import `Extrapolate` directly from
+ *   `react-native-reanimated` instead of `Animated` namespace.
  */
 export type Extrapolate = typeof _Extrapolate;
 /**
- * @deprecated Please import `SharedValue` directly from `react-native-reanimated` instead of `Animated` namespace.
+ * @deprecated Please import `SharedValue` directly from
+ *   `react-native-reanimated` instead of `Animated` namespace.
  */
 
 export type SharedValue<T> = _SharedValue<T>;
 /**
- * @deprecated Please import `DerivedValue` directly from `react-native-reanimated` instead of `Animated` namespace.
+ * @deprecated Please import `DerivedValue` directly from
+ *   `react-native-reanimated` instead of `Animated` namespace.
  */
 export type DerivedValue<T> = _DerivedValue<T>;
 /**
- * @deprecated Please import `Adaptable` directly from `react-native-reanimated` instead of `Animated` namespace.
+ * @deprecated Please import `Adaptable` directly from `react-native-reanimated`
+ *   instead of `Animated` namespace.
  */
 export type Adaptable<T> = _Adaptable<T>;
 /**
- * @deprecated Please import `TransformStyleTypes` directly from `react-native-reanimated` instead of `Animated` namespace.
- * */
+ * @deprecated Please import `TransformStyleTypes` directly from
+ *   `react-native-reanimated` instead of `Animated` namespace.
+ */
 export type TransformStyleTypes = _TransformStyleTypes;
 /**
- * @deprecated Please import `AdaptTransforms` directly from `react-native-reanimated` instead of `Animated` namespace.
- * */
+ * @deprecated Please import `AdaptTransforms` directly from
+ *   `react-native-reanimated` instead of `Animated` namespace.
+ */
 export type AdaptTransforms<T> = _AdaptTransforms<T>;
 /**
- * @deprecated Please import `AnimatedTransform` directly from `react-native-reanimated` instead of `Animated` namespace.
+ * @deprecated Please import `AnimatedTransform` directly from
+ *   `react-native-reanimated` instead of `Animated` namespace.
  */
 export type AnimatedTransform = _AnimatedTransform;
 /**
- * @deprecated Please import `AnimateStyle` directly from `react-native-reanimated` instead of `Animated` namespace.
- * */
+ * @deprecated Please import `AnimateStyle` directly from
+ *   `react-native-reanimated` instead of `Animated` namespace.
+ */
 export type AnimateStyle<S> = _AnimateStyle<S>;
 /**
- * @deprecated Please import `StylesOrDefault` directly from `react-native-reanimated` instead of `Animated` namespace.
- * */
+ * @deprecated Please import `StylesOrDefault` directly from
+ *   `react-native-reanimated` instead of `Animated` namespace.
+ */
 export type StylesOrDefault<S> = _StylesOrDefault<S>;
 /**
- * @deprecated Please import `AnimateProps` directly from `react-native-reanimated` instead of `Animated` namespace.
- * */
+ * @deprecated Please import `AnimateProps` directly from
+ *   `react-native-reanimated` instead of `Animated` namespace.
+ */
 export type AnimateProps<P extends object> = _AnimateProps<P>;
 /**
- * @deprecated Please import `EasingFunction` directly from `react-native-reanimated` instead of `Animated` namespace.
- * */
+ * @deprecated Please import `EasingFunction` directly from
+ *   `react-native-reanimated` instead of `Animated` namespace.
+ */
 export type EasingFunction = _EasingFunction;
 /**
- * @deprecated Please import `AnimatedScrollViewProps` directly from `react-native-reanimated` instead of `Animated` namespace.
- * */
+ * @deprecated Please import `AnimatedScrollViewProps` directly from
+ *   `react-native-reanimated` instead of `Animated` namespace.
+ */
 export type AnimatedScrollViewProps = _AnimatedScrollViewProps;
 /**
- * @deprecated Please import `FlatListPropsWithLayout` directly from `react-native-reanimated` instead of `Animated` namespace.
- * */
+ * @deprecated Please import `FlatListPropsWithLayout` directly from
+ *   `react-native-reanimated` instead of `Animated` namespace.
+ */
 export type FlatListPropsWithLayout<T> = _FlatListPropsWithLayout<T>;

packages/react-native-reanimated/src/Bezier.ts

@@ -3,9 +3,8 @@
 import { ReanimatedError } from './errors';
 
 /**
- * https://github.com/gre/bezier-easing
- * BezierEasing - use bezier curve for transition easing function
- * by Gaëtan Renaudeau 2014 - 2015 – MIT License
+ * https://github.com/gre/bezier-easing BezierEasing - use bezier curve for
+ * transition easing function by Gaëtan Renaudeau 2014 - 2015 – MIT License
  */
 
 // These values are established by empiricism with tests (tradeoff: performance VS precision)

packages/react-native-reanimated/src/Colors.ts

@@ -1,7 +1,6 @@
 'use strict';
 /**
- * Copied from:
- * react-native/Libraries/StyleSheet/normalizeColor.js
+ * Copied from: react-native/Libraries/StyleSheet/normalizeColor.js
  * react-native/Libraries/StyleSheet/processColor.js
  * https://github.com/wcandillon/react-native-redash/blob/master/src/Colors.ts
  */
@@ -524,11 +523,10 @@ export const rgbaColor = (
 };
 
 /**
- *
- * @param r - red value (0-255)
- * @param g - green value (0-255)
- * @param b - blue value (0-255)
- * @returns \{h: hue (0-1), s: saturation (0-1), v: value (0-1)\}
+ * @param r - Red value (0-255)
+ * @param g - Green value (0-255)
+ * @param b - Blue value (0-255)
+ * @returns `{h: hue (0-1), s: saturation (0-1), v: value (0-1)}`
  */
 export function RGBtoHSV(r: number, g: number, b: number): HSV {
   'worklet';
@@ -561,11 +559,10 @@ export function RGBtoHSV(r: number, g: number, b: number): HSV {
 }
 
 /**
- *
- * @param h - hue (0-1)
- * @param s - saturation (0-1)
- * @param v - value (0-1)
- * @returns \{r: red (0-255), g: green (0-255), b: blue (0-255)\}
+ * @param h - Hue (0-1)
+ * @param s - Saturation (0-1)
+ * @param v - Value (0-1)
+ * @returns `{r: red (0-255), g: green (0-255), b: blue (0-255)}`
  */
 function HSVtoRGB(h: number, s: number, v: number): RGB {
   'worklet';

packages/react-native-reanimated/src/ConfigHelper.ts

@@ -68,8 +68,8 @@ export interface ViewConfig {
   validAttributes: Record<string, unknown>;
 }
 /**
- * updates UI props whitelist for given view host instance
- * this will work just once for every view name
+ * Updates UI props whitelist for given view host instance this will work just
+ * once for every view name
  */
 
 export function adaptViewConfig(viewConfig: ViewConfig): void {