如何为自己的js项目生成API文档

如题，当自己写完了一个第三方库，准备发布时，总不能直接把一些使用方法以及传参说明写在README.md里吧

看到许多第三方库都有一个.d.ts文件，当我们使用这些第三方库时，在方法上安装ctrl+鼠标左键时就会跳转到对应.d.ts说明文档中

那么这个是咱们做的呢？难道是手动创建并编写的吗？不是吧？如果是手动创建的话，哪些大型项目那么多方法和文件模块，并且还是多人协作开发，不可能同步如此庞大的.d.ts文件，那么这个是怎么做的呢？

这个是使用TypeScript生成的，不是吧？那我用的不是TypeScript写的库不就不能生成了？

非也非也，即使不是用TypeScript写的项目也能生成.d.ts文件

只要你写的时候在方法上添加注释即可，注释关键字必须遵循JSDoc

JSDoc 中有很多关键字，这些关键字想必你多多少少会在其它第三方库的.d.ts文件中见过，如: @param @returns @author等，更多具体的请自行在JSDoc中查看

说了那么多，那么到底如何生成.d.ts文档呢？

举例我目前有一个/src/main.js，其中代码如下

COPY

/**
 * 代码来源于: https://github.com/Lete114/CardLink/blob/f4ab08b78625244d9515743e41c7e04f839e149f/src/main.js#L12
 * Determine if it is a ['https://', 'http://', '//'] protocol
 * @param {String} url Website url
 * @returns {Boolean}
 */
export default function isHttp(url) {
  return /^(https?:)?\/\//g.test(url)
}

只需一行命令即可，使用 npx 临时安装typescript，并调用typescript的命令生成.d.ts文档

注意其中-p是 npx 的命令，原名--package，具体请看官网https://docs.npmjs.com/cli/v8/commands/npx

src/**/*.js: 对 src 目录下的所有 js 文件生成.d.ts文件
--declaration: 生成相应的.d.ts文件
--allowJs: 允许编译 javascript 文件
--emitDeclarationOnly: 只输出 .d.ts 文件，不输出 JavaScript 文件
--outDir: 输出到指定的目录

COPY

1	npx -p typescript tsc src/**.js --declaration --allowJs --emitDeclarationOnly --outDir types

执行如上命令后就会先下载typescript，然后执行 tsc 命令，构建生成.d.ts 文件到types/main.d.ts

COPY

/**
 * 代码来源于: https://github.com/Lete114/CardLink/blob/f4ab08b78625244d9515743e41c7e04f839e149f/src/main.js#L12
 * Determine if it is a ['https://', 'http://', '//'] protocol
 * @param {String} url Website url
 * @returns {Boolean}
 */
export default function isHttp(url: string): boolean