chore(repo): Add eslint-plugin-jsdoc

.changeset/tasty-parrots-teach.md

@@ -0,0 +1,2 @@
+---
+---

.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

@@ -67,7 +67,9 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
   "types/user-organization-invitation-resource.mdx",
   "types/user-resource.mdx",
   "types/without.mdx",
+  "shared/api-url-from-publishable-key.mdx",
   "shared/build-clerk-js-script-attributes.mdx",
+  "shared/camel-to-snake.mdx",
   "shared/clerk-js-script-url.mdx",
   "shared/clerk-runtime-error.mdx",
   "shared/create-path-matcher.mdx",
@@ -79,11 +81,13 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
   "shared/fast-deep-merge-and-replace.mdx",
   "shared/get-clerk-js-major-version-or-tag.mdx",
   "shared/get-env-variable.mdx",
+  "shared/get-non-undefined-values.mdx",
   "shared/get-script-url.mdx",
   "shared/icon-image-url.mdx",
   "shared/in-browser.mdx",
   "shared/is-browser-online.mdx",
   "shared/is-clerk-runtime-error.mdx",
+  "shared/is-ipv4-address.mdx",
   "shared/is-publishable-key.mdx",
   "shared/is-staging.mdx",
   "shared/is-truthy.mdx",
@@ -96,6 +100,8 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
   "shared/paginated-resources.mdx",
   "shared/read-json-file.mdx",
   "shared/set-clerk-js-loading-error-package-name.mdx",
+  "shared/snake-to-camel.mdx",
+  "shared/titleize.mdx",
   "shared/to-sentence.mdx",
   "shared/use-clerk.mdx",
   "shared/use-organization-list-params.mdx",

eslint.config.mjs

@@ -11,6 +11,7 @@ import pluginSimpleImportSort from 'eslint-plugin-simple-import-sort';
 import pluginTurbo from 'eslint-plugin-turbo';
 import pluginUnusedImports from 'eslint-plugin-unused-imports';
 import pluginYml from 'eslint-plugin-yml';
+import pluginJsDoc from 'eslint-plugin-jsdoc';
 import globals from 'globals';
 import tseslint from 'typescript-eslint';
 
@@ -419,21 +420,32 @@ export default tseslint.config([
       'turbo/no-undeclared-env-vars': 'off',
     },
   },
-  ...pluginYml.configs['flat/recommended'],
   {
-    name: 'repo/.github',
-    // rules: {
-    // 'regex/invalid': [
-    //   'error',
-    //   [
-    //     {
-    //       regex: '^(?!.*\\$TURBO_ARGS( |$)).*turbo \\S+',
-    //       message: 'Invalid turbo CI command. Must contain `$TURBO_ARGS`',
-    //     },
-    //   ],
-    // ],
-    // },
+    name: 'repo/jsdoc',
+    ...pluginJsDoc.configs['flat/recommended-typescript'],
+    files: ['packages/shared/src/**/*.{ts,tsx}'],
+    ignores: ['**/__tests__/**'],
+    plugins: {
+      jsdoc: pluginJsDoc,
+    },
+    rules: {
+      ...pluginJsDoc.configs['flat/recommended-typescript'].rules,
+      'jsdoc/check-examples': 'off',
+      'jsdoc/informative-docs': 'warn',
+      'jsdoc/check-tag-names': ['warn', { definedTags: ['inline', 'unionReturnHeadings'], typed: false }],
+      'jsdoc/require-hyphen-before-param-description': 'warn',
+      'jsdoc/require-description': 'warn',
+      'jsdoc/require-description-complete-sentence': 'warn',
+      'jsdoc/require-param': ['warn', { ignoreWhenAllParamsMissing: true }],
+      'jsdoc/require-param-description': 'warn',
+      'jsdoc/require-returns': 'off',
+      'jsdoc/tag-lines': [
+        'warn',
+        'always',
+        { count: 1, applyToEndTag: false, startLines: 1, tags: { param: { lines: 'never' } } },
+      ],
+    },
   },
-
+  ...pluginYml.configs['flat/recommended'],
   configPrettier,
 ]);

package.json

@@ -94,6 +94,7 @@
     "eslint-import-resolver-typescript": "3.10.0",
     "eslint-plugin-import": "2.31.0",
     "eslint-plugin-jest": "28.11.0",
+    "eslint-plugin-jsdoc": "50.6.9",
     "eslint-plugin-jsx-a11y": "6.10.2",
     "eslint-plugin-playwright": "2.2.0",
     "eslint-plugin-react": "7.37.5",

packages/shared/src/apiUrlFromPublishableKey.ts

@@ -8,6 +8,12 @@ import {
 } from './constants';
 import { parsePublishableKey } from './keys';
 
+/**
+ * Get the correct API url based on the publishable key.
+ *
+ * @param publishableKey - The publishable key to parse.
+ * @returns One of Clerk's API URLs.
+ */
 export const apiUrlFromPublishableKey = (publishableKey: string) => {
   const frontendApi = parsePublishableKey(publishableKey)?.frontendApi;
 

packages/shared/src/underscore.ts

@@ -1,7 +1,8 @@
 /**
- * Converts an array of strings to a comma-separated sentence
- * @param items {Array<string>}
- * @returns {string} Returns a string with the items joined by a comma and the last item joined by ", or"
+ * Convert words to a sentence.
+ *
+ * @param items - An array of words to be joined.
+ * @returns A string with the items joined by a comma and the last item joined by ", or".
  */
 export const toSentence = (items: string[]): string => {
   // TODO: Once Safari supports it, use Intl.ListFormat
@@ -19,19 +20,41 @@ export const toSentence = (items: string[]): string => {
 const IP_V4_ADDRESS_REGEX =
   /^(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$/;
 
+/**
+ * Checks if a string is a valid IPv4 address.
+ *
+ * @returns True if the string is a valid IPv4 address, false otherwise.
+ */
 export function isIPV4Address(str: string | undefined | null): boolean {
   return IP_V4_ADDRESS_REGEX.test(str || '');
 }
 
+/**
+ * Converts the first character of a string to uppercase.
+ *
+ * @param str - The string to be converted.
+ * @returns The modified string with the rest of the string unchanged.
+ *
+ * @example
+ * ```ts
+ * titleize('hello world') // 'Hello world'
+ * ```
+ */
 export function titleize(str: string | undefined | null): string {
   const s = str || '';
   return s.charAt(0).toUpperCase() + s.slice(1);
 }
 
+/**
+ * Converts a string from snake_case to camelCase.
+ */
 export function snakeToCamel(str: string | undefined): string {
   return str ? str.replace(/([-_][a-z])/g, match => match.toUpperCase().replace(/-|_/, '')) : '';
 }
 
+/**
+ * Converts a string from camelCase to snake_case.
+ */
 export function camelToSnake(str: string | undefined): string {
   return str ? str.replace(/[A-Z]/g, letter => `_${letter.toLowerCase()}`) : '';
 }
@@ -73,6 +96,7 @@ const createDeepObjectTransformer = (transform: any) => {
  * Transforms camelCased objects/ arrays to snake_cased.
  * This function recursively traverses all objects and arrays of the passed value
  * camelCased keys are removed.
+ *
  * @function
  */
 export const deepCamelToSnake = createDeepObjectTransformer(camelToSnake);
@@ -81,13 +105,15 @@ export const deepCamelToSnake = createDeepObjectTransformer(camelToSnake);
  * Transforms snake_cased objects/ arrays to camelCased.
  * This function recursively traverses all objects and arrays of the passed value
  * camelCased keys are removed.
+ *
  * @function
  */
 export const deepSnakeToCamel = createDeepObjectTransformer(snakeToCamel);
 
 /**
- * Returns true for `true`, true, positive numbers.
- * Returns false for `false`, false, 0, negative integers and anything else.
+ * A function to determine if a value is truthy.
+ *
+ * @returns True for `true`, true, positive numbers. False for `false`, false, 0, negative integers and anything else.
  */
 export function isTruthy(value: unknown): boolean {
   // Return if Boolean
@@ -125,6 +151,9 @@ export function isTruthy(value: unknown): boolean {
   return false;
 }
 
+/**
+ * Get all non-undefined values from an object.
+ */
 export function getNonUndefinedValues<T extends object>(obj: T): Partial<T> {
   return Object.entries(obj).reduce((acc, [key, value]) => {
     if (value !== undefined) {