README_zh-Hans.md

rollup-plugin-keep-header-comment

API Documents

English · 简体中文

一个 rollup 插件，将源代码文件中第一个或符合指定模式的注释放置到输出文件的开头。

我在使用 tsdoc 搭配 @microsoft/api-extractor、@microsoft/api-documenter 为我的项目自动生成 API 文档时，如果不使用 --local 参数，会得到 Warning: dist/index.d.ts:4:1 - (ae-misplaced-package-tag) The @packageDocumentation comment must appear at the top of entry point *.d.ts file 。但是无论怎么调整源文件中的注释位置， rollup 都会将 import 语句自动放到文件开头。

因此开发了这个插件搭配 rollup 与 tsdoc 使用。只需要将本插件放在生成声明文件的 rollup 插件配置的最后即可。示例代码见 Usage 或者 Doc.

Install

install npm package

npm install gridfs-extra

or clone from Github

# ssh
git clone [email protected]:peachest/gridfs-extra.git

# http
git clone https://github.com/peachest/gridfs-extra.git

Usage

Put this plugin at the last after the dts plugin

import clear from "rollup-plugin-clear";
import json from "@rollup/plugin-json";
import nodeResolve from "@rollup/plugin-node-resolve";
import commonjs from "@rollup/plugin-commonjs";
import typescript from "rollup-plugin-typescript2";
import dts from "rollup-plugin-dts";
import keepHeaderComment from "rollup-plugin-keep-header-comment";

export default {
  plugins: [
    clear({targets: ["dist"]}),
    json(),
    nodeResolve({preferBuiltins: false}),
    commonjs(),
    typescript({tsconfig}),
    dts({tsconfig}),
    keepHeaderComment({
        sourcemap: true,
        pattern: /@packageDocumentation/
    })
  ]
}

Now you can put your packageDocumentation comment wherever you want in your source code:

import { OutputPlugin } from 'rollup';
/**
 * A rollup plugin to keep the header comments from source in the declaration file
 * @packageDocumentation
 */

rollup will generate dist/index.d.ts with comment at the start:

/**
 * A rollup plugin to keep the header comments from source in the declaration file
 * @packageDocumentation
 */
import { OutputPlugin } from 'rollup';

options：

• sourcemap（optional）：generate sourcemap for rollup, won’t generate sourcemap file in output directory

• pattern（optional）: if provided, comment which match this pattern will be shifted to the start of the file, otherwise the first comment will be shifted