refactor: add prettier-plugin-jsdoc

danielpza · danielpza · commit 0b5fd4cde2b4 · 2024-08-17T23:32:41.000-04:00
diff --git a/package.json b/package.json
@@ -73,6 +73,7 @@
     "eslint": "9.x",
     "globals": "^15.9.0",
     "prettier": "^3.3.3",
+    "prettier-plugin-jsdoc": "^1.3.0",
     "ts-patch": "^3.2.1",
     "typescript": "^5.5.4",
     "typescript-eslint": "^8.0.1"
@@ -83,5 +84,10 @@
   "dependencies": {
     "minimatch": "^10.0.1"
   },
+  "prettier": {
+    "plugins": [
+      "prettier-plugin-jsdoc"
+    ]
+  },
   "packageManager": "yarn@4.4.0+sha512.91d93b445d9284e7ed52931369bc89a663414e5582d00eea45c67ddc459a2582919eece27c412d6ffd1bd0793ff35399381cb229326b961798ce4f4cc60ddfdb"
 }
diff --git a/src/harmony/harmony-factory.ts b/src/harmony/harmony-factory.ts
@@ -14,9 +14,7 @@ export interface HarmonyFactory extends TS.NodeFactory {}
 // region: Utilities
 /* ****************************************************************************************************************** */
 
-/**
- * Creates a node factory compatible with TS v3+
- */
+/** Creates a node factory compatible with TS v3+ */
 export function createHarmonyFactory(context: TsTransformPathsContext): HarmonyFactory {
   return new Proxy(context.tsFactory ?? context.tsInstance, {
     get(target, prop) {
diff --git a/src/harmony/versions/four-seven.ts b/src/harmony/versions/four-seven.ts
@@ -1,6 +1,4 @@
-/**
- * Changes after this point: https://github.com/microsoft/TypeScript/wiki/API-Breaking-Changes#typescript-48
- */
+/** Changes after this point: https://github.com/microsoft/TypeScript/wiki/API-Breaking-Changes#typescript-48 */
 import type {
   default as TsCurrentModule,
   AssertClause,
diff --git a/src/harmony/versions/three-eight.ts b/src/harmony/versions/three-eight.ts
@@ -1,6 +1,4 @@
-/**
- * Changes after this point: https://github.com/microsoft/TypeScript/wiki/API-Breaking-Changes#typescript-40
- */
+/** Changes after this point: https://github.com/microsoft/TypeScript/wiki/API-Breaking-Changes#typescript-40 */
 import type {
   default as TsCurrentModule,
   EntityName,
diff --git a/src/transformer.ts b/src/transformer.ts
@@ -79,9 +79,7 @@ export default function transformer(
   program?: ts.Program,
   pluginConfig?: TsTransformPathsConfig,
   transformerExtras?: TransformerExtras,
-  /**
-   * Supply if manually transforming with compiler API via 'transformNodes' / 'transformModule'
-   */
+  /** Supply if manually transforming with compiler API via 'transformNodes' / 'transformModule' */
   manualTransformOptions?: {
     compilerOptions?: ts.CompilerOptions;
     fileNames?: string[];
diff --git a/src/types.ts b/src/types.ts
@@ -29,9 +29,7 @@ export interface TsTransformPathsConfig extends PluginConfig {
 /* ****************************************************************************************************************** */
 
 export interface TsTransformPathsContext {
-  /**
-   * TS Instance passed from ts-patch / ttypescript
-   */
+  /** TS Instance passed from ts-patch / ttypescript */
   readonly tsInstance: typeof ts;
   readonly tsVersionMajor: number;
   readonly tsVersionMinor: number;
diff --git a/src/utils/elide-import-export.ts b/src/utils/elide-import-export.ts
@@ -1,40 +1,39 @@
 /**
- * ----------------------------------------------------------------------------
  * UPDATE:
  *
  * TODO - In next major version, we can remove this file entirely due to TS PR 57223
  * https://github.com/microsoft/TypeScript/pull/57223
- * ----------------------------------------------------------------------------
  *
- * This file and its contents are due to an issue in TypeScript (affecting *at least* up to 4.1) which causes type
+ * This file and its contents are due to an issue in TypeScript (affecting _at least_ up to 4.1) which causes type
  * elision to break during emit for nodes which have been transformed. Specifically, if the 'original' property is set,
  * elision functionality no longer works.
  *
- * This results in module specifiers for types being output in import/export declarations in the compiled *JS files*
+ * This results in module specifiers for types being output in import/export declarations in the compiled _JS files_
  *
  * The logic herein compensates for that issue by recreating type elision separately so that the transformer can update
  * the clause with the properly elided information
  *
  * Issues:
- * @see https://github.com/LeDDGroup/typescript-transform-paths/issues/184
- * @see https://github.com/microsoft/TypeScript/issues/40603
- * @see https://github.com/microsoft/TypeScript/issues/31446
+ *
+ * - See https://github.com/LeDDGroup/typescript-transform-paths/issues/184
+ * - See https://github.com/microsoft/TypeScript/issues/40603
+ * - See https://github.com/microsoft/TypeScript/issues/31446
  *
  * @example
- * // a.ts
- * export type A = string
- * export const B = 2
+ *   // a.ts
+ *   export type A = string;
+ *   export const B = 2;
  *
- * // b.ts
- * import { A, B } from './b'
- * export { A } from './b'
+ *   // b.ts
+ *   import { A, B } from "./b";
+ *   export { A } from "./b";
  *
- * // Expected output for b.js
- * import { B } from './b'
+ *   // Expected output for b.js
+ *   import { B } from "./b";
  *
- * // Actual output for b.js
- * import { A, B } from './b'
- * export { A } from './b'
+ *   // Actual output for b.js
+ *   import { A, B } from "./b";
+ *   export { A } from "./b";
  */
 import { ImportOrExportDeclaration, VisitorContext } from "../types";
 import {
@@ -60,10 +59,10 @@ import {
 /* ****************************************************************************************************************** */
 
 /**
- * Get import / export clause for node (replicates TS elision behaviour for js files)
- * See notes in get-import-export-clause.ts header for why this is necessary
+ * Get import / export clause for node (replicates TS elision behaviour for js files) See notes in
+ * get-import-export-clause.ts header for why this is necessary
  *
- * @returns import or export clause or undefined if it entire declaration should be elided
+ * @returns Import or export clause or undefined if it entire declaration should be elided
  */
 export function elideImportOrExportDeclaration<T extends ImportOrExportDeclaration>(
   context: VisitorContext,
@@ -208,10 +207,7 @@ export function elideImportOrExportDeclaration(
     return !node.isTypeOnly && shouldEmitAliasDeclaration(node) ? node : undefined;
   }
 
-  /**
-   * Visits named exports, eliding it if it does not contain an export specifier that
-   * resolves to a value.
-   */
+  /** Visits named exports, eliding it if it does not contain an export specifier that resolves to a value. */
   function visitNamedExports(node: NamedExports, allowEmpty: boolean): VisitResult<NamedExports> | undefined {
     // Elide the named exports if all of its export specifiers were elided.
     const elements = visitNodes(node.elements, <Visitor>visitExportSpecifier, isExportSpecifier);
diff --git a/src/utils/resolve-module-name.ts b/src/utils/resolve-module-name.ts
@@ -10,17 +10,11 @@ import { getRelativePath } from "./get-relative-path";
 /* ****************************************************************************************************************** */
 
 export interface ResolvedModule {
-  /**
-   * Absolute path to resolved module
-   */
+  /** Absolute path to resolved module */
   resolvedPath: string | undefined;
-  /**
-   * Output path
-   */
+  /** Output path */
   outputPath: string;
-  /**
-   * Resolved to URL
-   */
+  /** Resolved to URL */
   isURL: boolean;
 }
 
@@ -117,9 +111,7 @@ function getResolvedSourceFile(context: VisitorContext, fileName: string): Sourc
 // region: Utils
 /* ****************************************************************************************************************** */
 
-/**
- * Resolve a module name
- */
+/** Resolve a module name */
 export function resolveModuleName(context: VisitorContext, moduleName: string): ResolvedModule | undefined {
   const { tsInstance, compilerOptions, sourceFile, config, rootDirs } = context;
 
diff --git a/src/utils/resolve-path-update-node.ts b/src/utils/resolve-path-update-node.ts
@@ -8,9 +8,7 @@ import { resolveModuleName } from "./resolve-module-name";
 // region: Node Updater Utility
 /* ****************************************************************************************************************** */
 
-/**
- * Gets proper path and calls updaterFn to get the new node if it should be updated
- */
+/** Gets proper path and calls updaterFn to get the new node if it should be updated */
 export function resolvePathAndUpdateNode(
   context: VisitorContext,
   node: ts.Node,
diff --git a/src/utils/ts-helpers.ts b/src/utils/ts-helpers.ts
@@ -7,9 +7,7 @@ import type { REGISTER_INSTANCE } from "ts-node";
 // region: TS Helpers
 /* ****************************************************************************************************************** */
 
-/**
- * Determine output file path for source file
- */
+/** Determine output file path for source file */
 export function getOutputDirForSourceFile(context: VisitorContext, sourceFile: SourceFile): string {
   const {
     tsInstance,
@@ -45,9 +43,7 @@ export function getOutputDirForSourceFile(context: VisitorContext, sourceFile: S
   return tsInstance.normalizePath(res);
 }
 
-/**
- * Determine if moduleName matches config in paths
- */
+/** Determine if moduleName matches config in paths */
 export function isModulePathsMatch(context: VisitorContext, moduleName: string): boolean {
   const {
     pathsPatterns,
@@ -56,9 +52,7 @@ export function isModulePathsMatch(context: VisitorContext, moduleName: string):
   return !!(pathsPatterns && matchPatternOrExact(pathsPatterns as readonly string[], moduleName));
 }
 
-/**
- * Create barebones EmitHost (for no-Program transform)
- */
+/** Create barebones EmitHost (for no-Program transform) */
 export function createSyntheticEmitHost(
   compilerOptions: ts.CompilerOptions,
   tsInstance: typeof ts,
@@ -77,9 +71,7 @@ export function createSyntheticEmitHost(
   } as unknown as ts.EmitHost;
 }
 
-/**
- * Get ts-node register info
- */
+/** Get ts-node register info */
 export function getTsNodeRegistrationProperties(tsInstance: typeof ts) {
   let tsNodeSymbol: typeof REGISTER_INSTANCE;
   try {
diff --git a/src/visitor.ts b/src/visitor.ts
@@ -23,17 +23,16 @@ const isRequire = ({ tsInstance }: VisitorContext, node: ts.Node): node is ts.Ca
  * Node Visitor
  * ****************************************************************************************************************** */
 
-/**
- * Visit and replace nodes with module specifiers
- */
+/** Visit and replace nodes with module specifiers */
 export function nodeVisitor(this: VisitorContext, node: ts.Node): ts.Node | undefined {
   const { factory, tsInstance, transformationContext } = this;
 
   /**
    * Update require / import functions
    *
-   * require('module')
-   * import('module')
+   * @example
+   *   require("module");
+   *   import("module");
    */
   if (isRequire(this, node) || isAsyncImport(this, node))
     return resolvePathAndUpdateNode(this, node, (<ts.StringLiteral>node.arguments[0]).text, (p) => {
@@ -67,7 +66,8 @@ export function nodeVisitor(this: VisitorContext, node: ts.Node): ts.Node | unde
   /**
    * Update ExternalModuleReference
    *
-   * import foo = require("foo");
+   * @example
+   *   import foo = require("foo");
    */
   if (tsInstance.isExternalModuleReference(node) && tsInstance.isStringLiteral(node.expression))
     return resolvePathAndUpdateNode(this, node, node.expression.text, (p) =>
@@ -77,8 +77,9 @@ export function nodeVisitor(this: VisitorContext, node: ts.Node): ts.Node | unde
   /**
    * Update ImportTypeNode
    *
-   * typeof import("./bar");
-   * import ("package").MyType;
+   * @example
+   *   typeof import("./bar");
+   *   import("package").MyType;
    */
   if (tsInstance.isImportTypeNode(node)) {
     const argument = node.argument as ts.LiteralTypeNode;
@@ -104,7 +105,8 @@ export function nodeVisitor(this: VisitorContext, node: ts.Node): ts.Node | unde
   /**
    * Update ImportDeclaration
    *
-   * import ... 'module';
+   * @example
+   *   import ... 'module';
    */
   if (tsInstance.isImportDeclaration(node) && node.moduleSpecifier && tsInstance.isStringLiteral(node.moduleSpecifier))
     return resolvePathAndUpdateNode(this, node, node.moduleSpecifier.text, (p) => {
@@ -123,7 +125,8 @@ export function nodeVisitor(this: VisitorContext, node: ts.Node): ts.Node | unde
   /**
    * Update ExportDeclaration
    *
-   * export ... 'module';
+   * @example
+   *   export ... 'module';
    */
   if (tsInstance.isExportDeclaration(node) && node.moduleSpecifier && tsInstance.isStringLiteral(node.moduleSpecifier))
     return resolvePathAndUpdateNode(this, node, node.moduleSpecifier.text, (p) => {
@@ -146,9 +149,7 @@ export function nodeVisitor(this: VisitorContext, node: ts.Node): ts.Node | unde
       );
     });
 
-  /**
-   * Update module augmentation
-   */
+  /** Update module augmentation */
   if (tsInstance.isModuleDeclaration(node) && tsInstance.isStringLiteral(node.name))
     return resolvePathAndUpdateNode(this, node, node.name.text, (p) =>
       factory.updateModuleDeclaration(node, node.modifiers, p, node.body),
diff --git a/test/projects/specific/src/tags.ts b/test/projects/specific/src/tags.ts
@@ -2,9 +2,7 @@
  * JSDoc
  * ****************************************************************************************************************** */
 
-/**
- * @no-transform-path
- */
+/** @no-transform-path */
 import * as skipTransform1 from "#root/index";
 
 /**
diff --git a/test/utils/helpers.ts b/test/utils/helpers.ts
@@ -63,9 +63,7 @@ function createReadFile(
 // region: Utilities
 /* ****************************************************************************************************************** */
 
-/**
- * Create TS Program with faux files and options
- */
+/** Create TS Program with faux files and options */
 export function createTsProgram(
   opt: CreateTsProgramOptions,
   transformerPath: string = config.transformerPath,
@@ -148,9 +146,7 @@ export function createTsSolutionBuilder(
   });
 }
 
-/**
- * Get emitted files for program
- */
+/** Get emitted files for program */
 export function getEmitResultFromProgram(program: ts.Program): EmittedFiles {
   const outputFiles: EmittedFiles = {};
   program.emit(undefined, createWriteFile(outputFiles));
diff --git a/yarn.lock b/yarn.lock
