feat: add jsdoc

Author: sxzz

package.json

@@ -85,7 +85,7 @@
     "magic-string": "^0.30.7",
     "picomatch": "^4.0.1",
     "unplugin": "^1.8.0",
-    "unplugin-replace": "link:/Users/kevin/Developer/open-source/unplugin-replace"
+    "unplugin-replace": "^0.2.1"
   },
   "devDependencies": {
     "@babel/types": "^7.24.0",

pnpm-lock.yaml

@@ -1,3 +1,9 @@
+/**
+ * This entry file is for exposing the core API.
+ *
+ * @module
+ */
+
 export {
   scanFiles,
   scanEnums,
@@ -6,3 +12,5 @@ export {
   type EnumDeclaration,
   type EnumData,
 } from './core/enum'
+
+export { type Options, resolveOptions } from './core/options'

src/api.ts

@@ -8,36 +8,56 @@ import picomatch from 'picomatch'
 import type { Expression, PrivateName } from '@babel/types'
 import type { OptionsResolved } from './options'
 
+/**
+ * Represents the scan options for the enum.
+ */
 export type ScanOptions = Pick<
   OptionsResolved,
   'scanDir' | 'scanMode' | 'scanPattern'
 >
 
+/**
+ * Represents a member of an enum.
+ */
 export interface EnumMember {
   readonly name: string
   readonly value: string | number
 }
 
+/**
+ * Represents a declaration of an enum.
+ */
 export interface EnumDeclaration {
   readonly id: string
   readonly range: readonly [start: number, end: number]
   readonly members: ReadonlyArray<EnumMember>
 }
 
+/**
+ * Represents the data of all enums.
+ */
 export interface EnumData {
   readonly declarations: {
     readonly [file: string]: ReadonlyArray<EnumDeclaration>
   }
   readonly defines: { readonly [id_key: `${string}.${string}`]: string }
 }
 
+/**
+ * Evaluates a JavaScript expression and returns the result.
+ * @param exp - The expression to evaluate.
+ * @returns The evaluated result.
+ */
 function evaluate(exp: string): string | number {
   return new Function(`return ${exp}`)()
 }
 
-// this is called in the build script entry once
-// so the data can be shared across concurrent Rollup processes
-export function scanEnums(options: ScanOptions) {
+/**
+ * Scans the specified directory for enums based on the provided options.
+ * @param options - The scan options for the enum.
+ * @returns The data of all enums found.
+ */
+export function scanEnums(options: ScanOptions): EnumData {
   const declarations: { [file: string]: EnumDeclaration[] } =
     Object.create(null)
 
@@ -184,6 +204,11 @@ export function scanEnums(options: ScanOptions) {
   return enumData
 }
 
+/**
+ * Scans the specified directory for files based on the provided options.
+ * @param options - The scan options for the files.
+ * @returns The list of files found.
+ */
 export function scanFiles(options: ScanOptions): string[] {
   if (options.scanMode === 'fs') {
     return fg.sync(options.scanPattern, {

src/core/enum.ts

@@ -1,29 +1,42 @@
 import process from 'node:process'
 import type { FilterPattern } from '@rollup/pluginutils'
 
+/**
+ * Represents the options for the plugin.
+ */
 export interface Options {
   include?: FilterPattern
   exclude?: FilterPattern
   enforce?: 'pre' | 'post' | undefined
   scanMode?: 'git' | 'fs'
   /**
+   * The directory to scan for enum files.
    * @default process.cwd()
    */
   scanDir?: string
   /**
+   * The pattern used to match enum files.
    * @default '**\/*.{cts,mts,ts,tsx}'
    */
   scanPattern?: string | string[]
 }
 
 type Overwrite<T, U> = Pick<T, Exclude<keyof T, keyof U>> & U
 
+/**
+ * Represents the resolved options for the plugin.
+ */
 export type OptionsResolved = Overwrite<
   Required<Options>,
   Pick<Options, 'enforce'>
 >
 
-export function resolveOption(options: Options): OptionsResolved {
+/**
+ * Resolves the options for the plugin.
+ * @param options - The options to resolve.
+ * @returns The resolved options.
+ */
+export function resolveOptions(options: Options): OptionsResolved {
   return {
     include: options.include || [/\.[cm]?[jt]sx?$/],
     exclude: options.exclude || [/node_modules/],

src/core/options.ts

@@ -1,3 +1,22 @@
-import unplugin from '.'
+/**
+ * This entry file is for esbuild plugin.
+ *
+ * @module
+ */
 
+import unplugin from './index'
+
+/**
+ * Esbuild plugin
+ *
+ * @example
+ * ```ts
+ * // esbuild.config.js
+ * import { build } from 'esbuild'
+ *
+ * build({
+ *   plugins: [require('unplugin-inline-enum/esbuild')()],
+ * })
+ * ```
+ */
 export default unplugin.esbuild

src/esbuild.ts

@@ -1,10 +1,18 @@
+/**
+ * This entry file is for main unplugin.
+ * @module
+ */
+
 import { createUnplugin } from 'unplugin'
 import { createFilter } from '@rollup/pluginutils'
 import MagicString from 'magic-string'
 import ReplacePlugin from 'unplugin-replace'
 import { type Options, resolveOption } from './core/options'
 import { scanEnums } from './core/enum'
 
+/**
+ * The main unplugin instance.
+ */
 export default createUnplugin<Options | undefined, true>(
   (rawOptions = {}, meta) => {
     const options = resolveOption(rawOptions)

src/index.ts

@@ -1,3 +1,22 @@
-import unplugin from '.'
+/**
+ * This entry file is for Rollup plugin.
+ *
+ * @module
+ */
 
+import unplugin from './index'
+
+/**
+ * Rollup plugin
+ *
+ * @example
+ * ```ts
+ * // rollup.config.js
+ * import Macros from 'unplugin-inline-enum/rollup'
+ *
+ * export default {
+ *   plugins: [Macros()],
+ * }
+ * ```
+ */
 export default unplugin.rollup

src/rollup.ts

@@ -1,3 +1,22 @@
-import unplugin from '.'
+/**
+ * This entry file is for Vite plugin.
+ *
+ * @module
+ */
 
+import unplugin from './index'
+
+/**
+ * Vite plugin
+ *
+ * @example
+ * ```ts
+ * // vite.config.ts
+ * import Macros from 'unplugin-inline-enum/vite'
+ *
+ * export default defineConfig({
+ *   plugins: [Macros()],
+ * })
+ * ```
+ */
 export default unplugin.vite

src/vite.ts

@@ -1,3 +1,20 @@
-import unplugin from '.'
+/**
+ * This entry file is for webpack plugin.
+ *
+ * @module
+ */
 
+import unplugin from './index'
+
+/**
+ * Webpack plugin
+ *
+ * @example
+ * ```ts
+ * // webpack.config.js
+ * module.exports = {
+ *  plugins: [require('unplugin-inline-enum/webpack')()],
+ * }
+ * ```
+ */
 export default unplugin.webpack