Enable recommended eslint-plugin-jsdoc rules (#5779)

* Upgraded jsdoc and typescript eslint deps

* Enabling recommended jsdoc in the SDK

* Updated @throws to ensure "freetext" mode is recognized.

* Fixing a lot of lint warnings

* Ran 'lint --fix'

* Fixing a lot of lint issues

* Ran lint --fix in @realm/react

package.json

@@ -68,19 +68,20 @@
   ],
   "dependencies": {
     "@react-native-community/eslint-config": "^3.1.0",
-    "@typescript-eslint/eslint-plugin": "^5.42.0",
-    "@typescript-eslint/parser": "^5.42.0",
+    "@typescript-eslint/eslint-plugin": "^5.60.0",
+    "@typescript-eslint/parser": "^5.60.0",
     "clang-format": "^1.8.0",
     "command-line-args": "^5.2.1",
-    "eslint": "^8.26.0",
-    "eslint-config-prettier": "^8.5.0",
+    "eslint": "^8.43.0",
+    "eslint-config-prettier": "^8.8.0",
     "eslint-plugin-flowtype": "^8.0.3",
     "eslint-plugin-header": "^3.1.1",
     "eslint-plugin-jasmine": "^4.1.3",
-    "eslint-plugin-jsdoc": "^39.5.0",
+    "eslint-plugin-jsdoc": "^46.2.6",
     "eslint-plugin-prettier": "^4.2.1",
-    "eslint-plugin-react": "^7.31.10",
+    "eslint-plugin-react-hooks": "^4.6.0",
     "eslint-plugin-react-native": "^4.0.0",
+    "eslint-plugin-react": "^7.32.2",
     "node-addon-api": "^6.0.0",
     "react-native": "0.71.7",
     "rollup": "^3.15.0",

packages/realm-react/.eslintrc.json

@@ -1,16 +1,19 @@
 {
-  "plugins": [
-    "eslint-plugin-tsdoc"
-  ],
   "parser": "@typescript-eslint/parser",
   "extends": [
     "plugin:@typescript-eslint/recommended",
-    "plugin:react-hooks/recommended"
+    "plugin:react-hooks/recommended",
+    "plugin:jsdoc/recommended-typescript"
   ],
   "rules": {
     "@typescript-eslint/explicit-function-return-type": "off",
     "react-hooks/rules-of-hooks": "error",
     "react-hooks/exhaustive-deps": "warn",
-    "tsdoc/syntax": "warn"
+    "jsdoc/check-tag-names": "off",
+    "jsdoc/require-jsdoc": "off",
+    "jsdoc/require-returns": "off",
+    "jsdoc/require-yields": "off",
+    "jsdoc/require-param": "off",
+    "jsdoc/no-undefined-types": "warn"
   }
 }

packages/realm-react/package.json

@@ -62,10 +62,6 @@
     "@types/react": "^18.0.21",
     "babel-jest": "^29.4.3",
     "babel-plugin-module-resolver": "^4.1.0",
-    "eslint": "^7.30.0",
-    "eslint-config-prettier": "^8.3.0",
-    "eslint-plugin-react-hooks": "^4.6.0",
-    "eslint-plugin-tsdoc": "^0.2.14",
     "fb-watchman": "^2.0.1",
     "jest": "^29.1.1",
     "metro-react-native-babel-preset": "0.73.9",

packages/realm-react/src/AppProvider.tsx

@@ -93,7 +93,6 @@ export const AppProvider: React.FC<AppProviderProps> = ({ children, appRef, ...a
 
 /**
  * Hook to access the current {@link Realm.App} from the {@link AppProvider} context.
- *
  * @throws if an AppProvider does not exist in the component’s ancestors
  */
 export const useApp = <

packages/realm-react/src/RealmProvider.tsx

@@ -33,7 +33,6 @@ type ProviderProps = PartialRealmConfiguration & {
 
 /**
  * Generates a `RealmProvider` given a {@link Realm.Configuration} and {@link React.Context}.
- *
  * @param realmConfig - The configuration of the Realm to be instantiated
  * @param RealmContext - The context that will contain the Realm instance
  * @returns a RealmProvider component that provides context to all context hooks
@@ -45,7 +44,6 @@ export function createRealmProvider(
   /**
    * Returns a Context Provider component that is required to wrap any component using
    * the Realm hooks.
-   *
    * @example
    * ```
    * const AppRoot = () => {
@@ -151,7 +149,6 @@ export function createRealmProvider(
 /**
  * Merge two configurations, creating a configuration using `configA` as the default,
  * merged with `configB`, with properties in `configB` overriding `configA`.
- *
  * @param configA - The default config object
  * @param configB - Config overrides object
  * @returns Merged config object
@@ -176,7 +173,6 @@ export function mergeRealmConfiguration(
 
 /**
  * Utility function that does a deep comparison (key: value) of object a with object b
- *
  * @param a - Object to compare
  * @param b - Object to compare
  * @returns True if the objects are identical

packages/realm-react/src/index.tsx

@@ -27,7 +27,6 @@ type RealmContext = {
   /**
    * The Provider component that is required to wrap any component using
    * the Realm hooks.
-   *
    * @example
    * ```
    * const AppRoot = () => {
@@ -53,12 +52,10 @@ type RealmContext = {
   RealmProvider: ReturnType<typeof createRealmProvider>;
   /**
    * Returns the instance of the {@link Realm} opened by the `RealmProvider`.
-   *
    * @example
    * ```
    * const realm = useRealm();
    * ```
-   *
    * @returns a realm instance
    */
   useRealm: ReturnType<typeof createUseRealm>;
@@ -70,7 +67,6 @@ type RealmContext = {
    * The result of this can be consumed directly by the `data` argument of any React Native
    * VirtualizedList or FlatList.  If the component used for the list's `renderItem` prop is {@link React.Memo}ized,
    * then only the modified object will re-render.
-   *
    * @example
    * ```tsx
    * // Return all collection items
@@ -79,7 +75,6 @@ type RealmContext = {
    * // Return all collection items sorted by name and filtered by category
    * const filteredAndSorted = useQuery(Object, (collection) => collection.filtered('category == $0',category).sorted('name'), [category]);
    * ```
-   *
    * @param type - The object type, depicted by a string or a class extending Realm.Object
    * @param query - A function that takes a {@link Realm.Collection} and returns a {@link Realm.Collection} of the same type.
    * This allows for filtering and sorting of the collection, before it is returned.
@@ -91,12 +86,10 @@ type RealmContext = {
    * Returns a {@link Realm.Object} from a given type and value of primary key.
    * The hook will update on any changes to the properties on the returned object
    * and return null if it either doesn't exists or has been deleted.
-   *
    * @example
    * ```
    * const object = useObject(ObjectClass, objectId);
    * ```
-   *
    * @param type - The object type, depicted by a string or a class extending {@link Realm.Object}
    * @param primaryKey - The primary key of the desired object which will be retrieved using {@link Realm.objectForPrimaryKey}
    * @returns either the desired {@link Realm.Object} or `null` in the case of it being deleted or not existing.
@@ -106,7 +99,6 @@ type RealmContext = {
 
 /**
  * Creates Realm React hooks and Provider component for a given Realm configuration
- *
  * @example
  * ```
  *class Task extends Realm.Object {
@@ -123,7 +115,6 @@ type RealmContext = {
  *
  *const {useRealm, useQuery, useObject, RealmProvider} = createRealmContext({schema: [Task]});
  * ```
- *
  * @param realmConfig - {@link Realm.Configuration} used to open the Realm
  * @returns An object containing a `RealmProvider` component, and `useRealm`, `useQuery` and `useObject` hooks
  */
@@ -150,7 +141,6 @@ const defaultContext = createRealmContext();
 /**
  * The Provider component that is required to wrap any component using
  * the Realm hooks.
- *
  * @example
  * ```
  * const AppRoot = () => {
@@ -173,12 +163,10 @@ export const RealmProvider = defaultContext.RealmProvider;
 
 /**
  * Returns the instance of the {@link Realm} opened by the `RealmProvider`.
- *
  * @example
  * ```
  * const realm = useRealm();
  * ```
- *
  * @returns a realm instance
  */
 export const useRealm = defaultContext.useRealm;
@@ -191,7 +179,6 @@ export const useRealm = defaultContext.useRealm;
  * The result of this can be consumed directly by the `data` argument of any React Native
  * VirtualizedList or FlatList.  If the component used for the list's `renderItem` prop is {@link React.Memo}ized,
  * then only the modified object will re-render.
- *
  * @example
  * ```tsx
  * // Return all collection items
@@ -200,7 +187,6 @@ export const useRealm = defaultContext.useRealm;
  * // Return all collection items sorted by name and filtered by category
  * const filteredAndSorted = useQuery(Object, (collection) => collection.filtered('category == $0',category).sorted('name'), [category]);
  * ```
- *
  * @param type - The object type, depicted by a string or a class extending Realm.Object
  * @param query - A function that takes a {@link Realm.Collection} and returns a {@link Realm.Collection} of the same type.
  * This allows for filtering and sorting of the collection, before it is returned.
@@ -213,12 +199,10 @@ export const useQuery = defaultContext.useQuery;
  * Returns a {@link Realm.Object} from a given type and value of primary key.
  * The hook will update on any changes to the properties on the returned object
  * and return null if it either doesn't exists or has been deleted.
- *
  * @example
  * ```
  * const object = useObject(ObjectClass, objectId);
  * ```
- *
  * @param type - The object type, depicted by a string or a class extending {@link Realm.Object}
  * @param primaryKey - The primary key of the desired object which will be retrieved using {@link Realm.objectForPrimaryKey}
  * @returns either the desired {@link Realm.Object} or `null` in the case of it being deleted or not existing.

packages/realm-react/src/useAuth.tsx

@@ -32,7 +32,6 @@ interface UseAuth {
 
   /**
    * Log in with the Anonymous authentication provider.
-   *
    * @returns A `Realm.User` instance for the logged in user.
    * @see https://www.mongodb.com/docs/atlas/app-services/authentication/anonymous/
    */
@@ -106,7 +105,6 @@ interface UseAuth {
  * `loginResult.pending` to render a spinner when login is in progress, without
  * needing to pass that state around or store it somewhere global in their app
  * code.
- *
  * @returns An object containing operations and state for authenticating with an Atlas App.
  */
 export function useAuth(): UseAuth {

packages/realm-react/src/useEmailPasswordAuth.tsx

@@ -26,57 +26,49 @@ interface UseEmailPasswordAuth {
   /**
    * Convenience function to log in a user with an email and password - users
    * could also call `logIn(Realm.Credentials.emailPassword(email, password))`.
-   *
    * @see https://www.mongodb.com/docs/realm/sdk/react-native/manage-users/manage-email-password-users/#add-appprovider-to-work-with-email-password-users
    */
   logIn(credentials: { email: string; password: string }): void;
 
   /**
    * Register a new user.
-   *
    * @see https://www.mongodb.com/docs/realm/sdk/react-native/manage-users/manage-email-password-users/#register-a-new-user-account
    */
   register(args: { email: string; password: string }): void;
 
   /**
    * Confirm a user's account by providing the `token` and `tokenId` received.
-   *
    * @see https://www.mongodb.com/docs/realm/sdk/react-native/manage-users/manage-email-password-users/#confirm-a-new-user-s-email-address
    */
   confirm(args: { token: string; tokenId: string }): void;
 
   /**
    * Resend a user's confirmation email.
-   *
    * @see https://www.mongodb.com/docs/realm/sdk/react-native/manage-users/manage-email-password-users/#resend-a-confirmation-email
    */
   resendConfirmationEmail(args: { email: string }): void;
 
   /**
    * Retry the custom confirmation function for a given user.
-   *
    * @see https://www.mongodb.com/docs/realm/sdk/react-native/manage-users/manage-email-password-users/#retry-a-user-confirmation-function
    */
   retryCustomConfirmation(args: { email: string }): void;
 
   /**
    * Send a password reset email for a given user.
-   *
    * @see https://www.mongodb.com/docs/realm/sdk/react-native/manage-users/manage-email-password-users/#send-a-password-reset-email
    */
   sendResetPasswordEmail(args: { email: string }): void;
 
   /**
    * Complete resetting a user's password.
-   *
    * @see https://www.mongodb.com/docs/realm/sdk/react-native/manage-users/manage-email-password-users/#send-a-password-reset-email
    */
   resetPassword(args: { token: string; tokenId: string; password: string }): void;
 
   /**
    * Call the configured password reset function, passing in any additional
    * arguments to the function.
-   *
    * @see https://www.mongodb.com/docs/realm/sdk/react-native/manage-users/manage-email-password-users/#call-a-password-reset-function
    */
   callResetPasswordFunction<Args extends unknown[] = []>(
@@ -89,7 +81,6 @@ interface UseEmailPasswordAuth {
 
   /**
    * Log out the current user.
-   *
    * @see https://www.mongodb.com/docs/realm/sdk/react-native/manage-users/authenticate-users/#log-a-user-out
    */
   logOut(): void;
@@ -113,7 +104,6 @@ interface UseEmailPasswordAuth {
  * `result.pending` to render a spinner when login is in progress, without
  * needing to pass that state around or store it somewhere global in their app
  * code.
- *
  * @returns An object containing operations and state related to Email/Password authentication.
  */
 export function useEmailPasswordAuth(): UseEmailPasswordAuth {

packages/realm-react/src/useObject.tsx

@@ -22,7 +22,6 @@ import { CollectionCallback, getObjectForPrimaryKey, getObjects } from "./helper
 
 /**
  * Generates the `useObject` hook from a given `useRealm` hook.
- *
  * @param useRealm - Hook that returns an open Realm instance
  * @returns useObject - Hook that is used to gain access to a single Realm object from a primary key
  */

packages/realm-react/src/useQuery.tsx

@@ -27,7 +27,6 @@ type DependencyList = ReadonlyArray<unknown>;
 
 /**
  * Generates the `useQuery` hook from a given `useRealm` hook.
- *
  * @param useRealm - Hook that returns an open Realm instance
  * @returns useObject - Hook that is used to gain access to a {@link Realm.Collection}
  */

packages/realm-react/src/useRealm.tsx

@@ -21,7 +21,6 @@ import { useContext } from "react";
 /**
  * Generates a `useRealm` hook given a RealmContext.  This allows access to the {@link Realm}
  * instance anywhere within the RealmProvider.
- *
  * @param RealmContext - The context containing the {@link Realm} instance
  * @returns useRealm - Hook that is used to gain access to the {@link Realm} instance
  */

packages/realm/.eslintignore

@@ -1,3 +1,4 @@
 dist/
-generated/types/
+docs/
 bindgen/vendor/realm-core/
+src/tests/realms/

packages/realm/.eslintrc.json

@@ -1,11 +1,18 @@
 {
   "parser": "@typescript-eslint/parser",
   "extends": [
-    "plugin:@typescript-eslint/recommended"
+    "plugin:@typescript-eslint/recommended",
+    "plugin:jsdoc/recommended-typescript"
   ],
   "rules": {
     "@typescript-eslint/explicit-function-return-type": "off",
     "no-console": "error",
-    "sort-imports": ["warn", { "ignoreDeclarationSort": true }]
+    "sort-imports": ["warn", { "ignoreDeclarationSort": true }],
+    "jsdoc/check-tag-names": "off",
+    "jsdoc/require-jsdoc": "off",
+    "jsdoc/require-returns": "off",
+    "jsdoc/require-yields": "off",
+    "jsdoc/require-param": "off",
+    "jsdoc/no-undefined-types": "warn"
   }
 }