chore: configure eslint-jsdoc-plugin (#883)

## Description

This PR configures eslint-jsdoc-plugin so:
- JSDocs are consistent throughout codebase and jsdocs are consistent
with method/interface signature
- there is defined set of `@category` tag values to prevent typos and
generating additional sections in docs
- fixed few jsdocs manually

### Introduces a breaking change?

- [ ] Yes
- [x] No

### Type of change

- [ ] Bug fix (change which fixes an issue)
- [ ] New feature (change which adds functionality)
- [ ] Documentation update (improves or adds clarity to existing
documentation)
- [x] Other (chores, tests, code style improvements etc.)

### Tested on

- [ ] iOS
- [ ] Android

### Testing instructions

- try to break some jsdocs (e. g. remove `@returns` tag, set `@category`
to some value outside of values defined in `eslintrc.js`, change
`@param` tag so it does not match signature) and see if eslint catches
these errors.
- build and open docs locally and check out if api reference is valid

### Screenshots

<!-- Add screenshots here, if applicable -->

### Related issues

#831 

### Checklist

- [x] I have performed a self-review of my code
- [ ] I have commented my code, particularly in hard-to-understand areas
- [ ] I have updated the documentation accordingly
- [x] My changes generate no new warnings

### Additional notes

**NOTE:** for now I switched off required destructured params as that's
the convention we are mostly using, but we could move to destructured
params eventually.

---------

Co-authored-by: Mateusz Słuszniak <mateusz.sluszniak@swmansion.com>
Co-authored-by: Mateusz Sluszniak <56299341+msluszniak@users.noreply.github.com>

Author: mateuszlampert

.cspell-wordlist.txt

@@ -179,3 +179,4 @@ nˈɛvəɹ
 ɹˈiᵊli
 ˈɛniwˌʌn
 ˈɛls
+Synchronizable

.eslintrc.js

@@ -1,5 +1,33 @@
 const path = require('path');
 
+const VALID_CATEGORIES = [
+  'Base Classes',
+  'Hooks',
+  'Interfaces',
+  'Models - Classification',
+  'Models - Image Embeddings',
+  'Models - Image Generation',
+  'Models - LMM',
+  'Models - Object Detection',
+  'Models - Instance Segmentation',
+  'Models - Semantic Segmentation',
+  'Models - Speech To Text',
+  'Models - Style Transfer',
+  'Models - Text Embeddings',
+  'Models - Text to Speech',
+  'Models - VLM',
+  'Models - Voice Activity Detection',
+  'OCR Supported Alphabets',
+  'TTS Supported Voices',
+  'Types',
+  'Typescript API',
+  'Utils',
+  'Utilities - General',
+  'Utilities - LLM',
+];
+
+const CATEGORY_TAG_MATCH = `^(${VALID_CATEGORIES.join('|')})$`;
+
 module.exports = {
   parserOptions: {
     requireConfigFile: false,
@@ -13,6 +41,7 @@ module.exports = {
     'plugin:@cspell/recommended',
     'plugin:prettier/recommended',
     'plugin:markdown/recommended-legacy',
+    'plugin:jsdoc/recommended-typescript',
   ],
   rules: {
     'react/react-in-jsx-scope': 'off',
@@ -33,8 +62,28 @@ module.exports = {
       },
     ],
     'camelcase': 'error',
+    'jsdoc/require-jsdoc': 'off',
+    'jsdoc/require-param': ['error', { checkDestructured: false }],
+    'jsdoc/check-param-names': ['error', { checkDestructured: false }],
+    'jsdoc/require-yields-type': 'off',
+    'jsdoc/require-yields-description': 'warn',
+    'jsdoc/check-tag-names': ['error', { definedTags: ['property'] }],
+    'jsdoc/match-description': [
+      'error',
+      {
+        contexts: ['any'],
+        mainDescription: false,
+        tags: {
+          category: {
+            message:
+              '@category must be one of categories defined in .eslintrc.js',
+            match: CATEGORY_TAG_MATCH,
+          },
+        },
+      },
+    ],
   },
-  plugins: ['prettier', 'markdown'],
+  plugins: ['prettier', 'markdown', 'jsdoc'],
   overrides: [
     {
       files: ['packages/react-native-executorch/src/**/*.{js,jsx,ts,tsx}'],
@@ -58,4 +107,11 @@ module.exports = {
     },
   ],
   ignorePatterns: ['node_modules/', 'lib/'],
+  settings: {
+    jsdoc: {
+      tagNamePreference: {
+        typeParam: 'typeParam',
+      },
+    },
+  },
 };

apps/computer-vision/components/ImageWithMasks.tsx

@@ -38,6 +38,8 @@ export interface DisplayInstance {
  * Convert raw segmentation output into lightweight display instances.
  * Call this eagerly (in the forward callback) so raw Uint8Array masks
  * can be garbage-collected immediately.
+ * @param rawInstances - Array of raw segmentation instances with mask buffers to convert.
+ * @returns Array of lightweight {@link DisplayInstance} objects with pre-rendered Skia images.
  */
 export function buildDisplayInstances(
   rawInstances: {

apps/speech/screens/TextToSpeechLLMScreen.tsx

@@ -30,6 +30,7 @@ interface TextToSpeechLLMProps {
 /**
  * Converts an audio vector (Float32Array) to an AudioBuffer for playback
  * @param audioVector - The generated audio samples from the model
+ * @param audioContext - The audio context used to create the buffer.
  * @param sampleRate - The sample rate (default: 24000 Hz for Kokoro)
  * @returns AudioBuffer ready for playback
  */

apps/speech/screens/TextToSpeechScreen.tsx

@@ -53,6 +53,7 @@ import SWMIcon from '../assets/swm_icon.svg';
 /**
  * Converts an audio vector (Float32Array) to an AudioBuffer for playback
  * @param audioVector - The generated audio samples from the model
+ * @param audioContext - An optional AudioContext to create the buffer in. If not provided, a new one will be created.
  * @param sampleRate - The sample rate (default: 24000 Hz for Kokoro)
  * @returns AudioBuffer ready for playback
  */

docs/docs/03-hooks/02-computer-vision/visioncamera-integration.md

@@ -184,20 +184,17 @@ export default function App() {
   const frameOutput = useFrameOutput({
     pixelFormat: 'rgb',
     dropFramesWhileBusy: true,
-    onFrame: useCallback(
-      (frame: Frame) => {
-        'worklet';
-        try {
-          if (!runOnFrame) return;
-          const isFrontCamera = cameraPositionSync.getDirty() === 'front';
-          const result = runOnFrame(frame, isFrontCamera);
-          // ... handle result
-        } finally {
-          frame.dispose();
-        }
-      },
-      [runOnFrame]
-    ),
+    onFrame: useCallback((frame: Frame) => {
+      'worklet';
+      try {
+        if (!runOnFrame) return;
+        const isFrontCamera = cameraPositionSync.getDirty() === 'front';
+        const result = runOnFrame(frame, isFrontCamera);
+        // ... handle result
+      } finally {
+        frame.dispose();
+      }
+    }, []),
   });
 
   // ...

docs/docusaurus.config.js

@@ -18,6 +18,7 @@ const config = {
   projectName: 'react-native-executorch',
 
   onBrokenLinks: 'throw',
+  onBrokenAnchors: 'throw',
   markdown: {
     hooks: {
       onBrokenMarkdownLinks: 'warn',

package.json

@@ -22,6 +22,7 @@
     "cspell": "^8.19.0",
     "eslint": "^8.57.0",
     "eslint-plugin-ft-flow": "^2.0.3",
+    "eslint-plugin-jsdoc": "^62.7.1",
     "eslint-plugin-markdown": "^5.1.0",
     "eslint-plugin-prettier": "^5.0.1",
     "expo-router": "~6.0.17",

packages/bare-resource-fetcher/src/ResourceFetcher.ts

@@ -4,9 +4,7 @@
  * This module provides functions to download and manage files stored in the application's document directory
  * inside the `react-native-executorch/` directory. These utilities help manage storage and clean up downloaded
  * files when they are no longer needed.
- *
  * @category Utilities - General
- *
  * @remarks
  * **Key Functionality:**
  * - **Download Control**: Pause, resume, and cancel operations through:
@@ -102,15 +100,13 @@ interface BareResourceFetcherInterface extends ResourceFetcherAdapter {
 /**
  * This module provides functions to download and work with downloaded files stored in the application's document directory inside the `react-native-executorch/` directory.
  * These utilities can help you manage your storage and clean up the downloaded files when they are no longer needed.
- *
  * @category Utilities - General
  */
 export const BareResourceFetcher: BareResourceFetcherInterface = {
   downloads: new Map<ResourceSource, DownloadResource>(), //map of currently downloading (or paused) files, if the download was started by .fetch() method.
 
   /**
    * Fetches resources (remote URLs, local files or embedded assets), downloads or stores them locally for use by React Native ExecuTorch.
-   *
    * @param callback - Optional callback to track progress of all downloads, reported between 0 and 1.
    * @param sources - Multiple resources that can be strings, asset references, or objects.
    * @returns If the fetch was successful, it returns a promise which resolves to an array of local file paths for the downloaded/stored resources (without file:// prefix).
@@ -320,7 +316,6 @@ export const BareResourceFetcher: BareResourceFetcherInterface = {
 
   /**
    * Pauses an ongoing download of files.
-   *
    * @param sources - The resource identifiers used when calling `fetch`.
    * @returns A promise that resolves once the download is paused.
    */
@@ -331,7 +326,6 @@ export const BareResourceFetcher: BareResourceFetcherInterface = {
 
   /**
    * Resumes a paused download of files.
-   *
    * @param sources - The resource identifiers used when calling fetch.
    * @returns If the fetch was successful, it returns a promise which resolves to an array of local file paths for the downloaded resources (without file:// prefix).
    * If the fetch was again interrupted by `pauseFetching` or `cancelFetching`, it returns a promise which resolves to `null`.
@@ -343,7 +337,6 @@ export const BareResourceFetcher: BareResourceFetcherInterface = {
 
   /**
    * Cancels an ongoing/paused download of files.
-   *
    * @param sources - The resource identifiers used when calling `fetch()`.
    * @returns A promise that resolves once the download is canceled.
    */
@@ -366,7 +359,6 @@ export const BareResourceFetcher: BareResourceFetcherInterface = {
 
   /**
    * Lists all the downloaded files used by React Native ExecuTorch.
-   *
    * @returns A promise, which resolves to an array of URIs for all the downloaded files.
    */
   async listDownloadedFiles() {
@@ -376,7 +368,6 @@ export const BareResourceFetcher: BareResourceFetcherInterface = {
 
   /**
    * Lists all the downloaded models used by React Native ExecuTorch.
-   *
    * @returns A promise, which resolves to an array of URIs for all the downloaded models.
    */
   async listDownloadedModels() {
@@ -386,7 +377,6 @@ export const BareResourceFetcher: BareResourceFetcherInterface = {
 
   /**
    * Deletes downloaded resources from the local filesystem.
-   *
    * @param sources - The resource identifiers used when calling `fetch`.
    * @returns A promise that resolves once all specified resources have been removed.
    */
@@ -404,7 +394,6 @@ export const BareResourceFetcher: BareResourceFetcherInterface = {
 
   /**
    * Fetches the info about files size. Works only for remote files.
-   *
    * @param sources - The resource identifiers (URLs).
    * @returns A promise that resolves to combined size of files in bytes.
    */
@@ -635,10 +624,8 @@ export const BareResourceFetcher: BareResourceFetcherInterface = {
 
   /**
    * Reads the contents of a file as a string.
-   *
    * @param path - Absolute file path to read.
    * @returns A promise that resolves to the file contents as a string.
-   *
    * @remarks
    * **REQUIRED**: Used internally for reading configuration files (e.g., tokenizer configs).
    */

packages/bare-resource-fetcher/src/ResourceFetcherUtils.ts

@@ -18,7 +18,6 @@ export type { ResourceSourceExtended };
 
 /**
  * Utility functions for fetching and managing resources.
- *
  * @category Utilities - General
  */
 export namespace ResourceFetcherUtils {