Electron-TypeScript中如何复用函数JSDoc至重声明函数？

要实现JSDoc的单一数据源，无需重复粘贴注释，可以通过TypeScript类型复用让重声明的函数自动继承原函数的文档注释，具体有两种常用方案：

方案1：利用typeof提取原函数类型 #

直接提取原函数的类型，让preload中的重声明函数复用该类型，TypeScript会自动保留原函数的JSDoc注释。

步骤1：在dbinteract.ts中导出函数和其类型 #

/** 
 * Adds a new user to the database.
 * @param {AddUserProps} userinfo An object containing all user info besides `id`.
 * @returns The new UserData object from database, including `id`.
 * */
export function addUser(userinfo: AddUserProps) { 
  // ...函数实现
}

// 导出函数类型，自动继承原函数的JSDoc
export type AddUserFn = typeof addUser;

步骤2：在preload.ts中复用该类型 #

import type { AddUserFn } from './dbfunc/dbinteract';
const { contextBridge, ipcRenderer } = require('electron');

contextBridge.exposeInMainWorld('dbfunc', {
    // 通过类型断言让重声明的函数继承原类型的JSDoc
    addUser: ((userinfo) => ipcRenderer.invoke('db:addUser', userinfo)) as AddUserFn,
});

方案2：定义统一的API接口 #

把数据库操作的函数签名和JSDoc写在一个接口里，所有实现（包括原函数和IPC桥函数）都遵循这个接口，实现注释的统一管理。

步骤1：在dbinteract.ts中定义接口并实现 #

/** 
 * Adds a new user to the database.
 * @param userinfo An object containing all user info besides `id`.
 * @returns The new UserData object from database, including `id`.
 * */
export interface DBFunctions {
  addUser: (userinfo: AddUserProps) => Promise<UserData>;
}

// 实现接口，自动继承接口的JSDoc
export const dbinteract: DBFunctions = {
  addUser(userinfo) {
    // ...函数实现
  }
};

步骤2：主进程中使用接口类型 #

import { app, ipcMain } from 'electron';
import { dbinteract, type DBFunctions } from './dbfunc/dbinteract';

app.on('ready', () => {
  ipcMain.handle('db:addUser', (event, userinfo) => dbinteract.addUser(userinfo));
});

步骤3：preload.ts中复用接口定义暴露对象 #

import type { DBFunctions } from './dbfunc/dbinteract';
const { contextBridge, ipcRenderer } = require('electron');

// 定义符合接口的对象，自动继承JSDoc
const exposedDbFunc: DBFunctions = {
  addUser: (userinfo) => ipcRenderer.invoke('db:addUser', userinfo),
};

contextBridge.exposeInMainWorld('dbfunc', exposedDbFunc);

补充：让渲染器也能获取JSDoc #

如果渲染器使用TypeScript，需要在全局类型声明中定义window.dbfunc的类型，这样在渲染器中调用时也能看到注释：

创建src/types/global.d.ts文件：

import type { DBFunctions } from '../dbfunc/dbinteract';

declare global {
  interface Window {
    dbfunc: DBFunctions;
  }
}

这样无论在preload还是渲染器中，调用dbfunc.addUser时都能自动显示原JSDoc注释，完全实现单一数据源，无需重复编写注释。

内容的提问来源于stack exchange，提问作者Josh Silveous