背景

在编写ts库的实践过程中，发现导出的函数只有简短的提示，很不友好，

要是能保留jsdoc的中文注释就好了，实现效果如下

实现步骤

1. tsconfig.json中"removeComments": false, 这样就保证了ts编译后注释保留
2. 书写带有jsdoc的函数此处就开始有问题了

写法1

//src/index.ts打包入口文件
import utils from "./utils";
export default{
    utils
}

//src/utils/index.ts
/**
 * @param href 地址URL
 * @returns 返回一个对象，包含URL中的参数名和参数值
 */
function getParamsFromHref(href:string):Record<string,string>{
  const result:Record<string,string> = {}
  const url=decodeURIComponent(href)
  const params = url.split('?')[1]
  if (params) {
    const pairs = params.split('&')
    for (const pair of pairs) {
      const [key, value] = pair.split('=')
      result[key] = value
    }
  }
  return result
}

export default{
  getParamsFromHref
}

使用如上写法，看起来没啥问题，但是发现打包后的.d.ts文件

// dist/types/index.d.ts
declare const _default: {
    utils: {
        getParamsFromHref: (href: string) => Record<string, string>;
    };
};
export default _default;

// dist/types/utils/index.d.ts
/**
 * @param href 地址URL
 * @returns 返回一个对象，包含URL中的参数名和参数值
 */
declare function getParamsFromHref(href: string): Record<string, string>;
declare const _default: {
    getParamsFromHref: typeof getParamsFromHref;
};
export default _default;

jsdoc文件紧靠着getParamsFromHref的声明位置，默认导出会生成 export default 的声明,注释丢失的原因：嵌套对象的注释不会保留在 .d.ts 文件中，建议直接导出函数或显式定义类型接口。
这样导致使用的函数MyLibrary.utils.getParamsFromHref没有jsdoc的智能提示

最终写法

使用具名导出
utils/index.ts

/**
 * @param href 地址URL
 * @returns 返回一个对象，包含URL中的参数名和参数值
 */
export function getParamsFromHref(href:string):Record<string,string>{
  const result:Record<string,string> = {}
  const url=decodeURIComponent(href)
  const params = url.split('?')[1]
  if (params) {
    const pairs = params.split('&')
    for (const pair of pairs) {
      const [key, value] = pair.split('=')
      result[key] = value
    }
  }
  return result
}

src/index.ts

import * as utils from "./utils";
console.log(`output->hello`,'hello')
export default{
    utils
}

打包后的类型文件

// types/index.d.ts
import * as utils from "./utils";
declare const _default: {
    utils: typeof utils;
};
export default _default;

// types/utils/index.d.ts
/**
 * @param href 地址URL
 * @returns 返回一个对象，包含URL中的参数名和参数值
 */
export declare function getParamsFromHref(href: string): Record<string, string>;

总结

在编写ts库的时候，模块化导出，最好是使用export function进行单独导出，然后再到使用的地方使用import {}或者import * as进行导入，这样的实践策略，能够保持jsdoc的提示

• export function 的优势

  • 保留 JSDoc 注释
    当你使用 export function 单独导出时，TypeScript 会直接在 .d.ts 文件中生成对应的 export declare function，并保留 JSDoc 注释。
  • 更好的 Tree Shaking 支持
    单独导出的函数可以被 Tree Shaking 更高效地优化。
    如果用户只需要 getParamsFromHref，可以通过 import { getParamsFromHref } from ‘your-library’ 导入，而不需要加载整个模块。

• export default 的问题

  • 注释丢失
    当你使用 export default 导出一个对象时，TypeScript 会将对象中的函数嵌套在 export default 的类型声明中。
  • 如果模块中包含多个功能，用户无法只导入某个特定功能。