Open jonnycornwell opened 3 years ago
@jonnycornwell This is a great suggestion. We would definitely use this feature in our own projects.
Design:
How should API Extractor obtain the header? Some possible options:
"fileHeader"
under the "dtsRollup"
section./*
or //
but not /**
) in the entry point file (e.g. src/index.d.ts
). If that comment contains the word "Copyright" or "License", then guess that it is probably the copyright banner. For such a heuristic, there should be a setting to disable it (e.g. "disableHeaderDetection": true
in api-extractor.json)"preserveFirstCommentAsHeader": true
under "dtsRollup"
, and then whatever code comment appears at the top of the entry point (e.g. src/index.d.ts
) will be copied to be the first comment in the .d.ts rollup. This would be an off-by-default setting.@copyright
?)Edit: The @packageDocumentation
comment is already preserved in the output, so I changed the TSDoc tag name.
We could also combine ideas 2 and 3:
"preserveFirstCommentAsHeader"
setting has three possible values:
"auto"
(the default) - preserves the first comment from the entry point, but only if it contains the word "copyright" or "license" and is not a /**
comment"never"
- the feature is disabled"always"
- the first comment is always preserved(The reason for ignoring /**
comments is that otherwise we need to consider: (1) what if the first comment is the @packageDocumentation
comment? (2) what if the first comment is actually API docs and doesn't make sense as a file header?)
Some edge cases:
"always"
report an error? (I slightly favor Yes)/**
comment, should "always"
copy it anyway? Yes means if it is the @packageDocumentation
comment or an API comment, it might get copied twice. No means developers need to properly format their copyright comment. (I slightly favor No)Following up on this since the issue hasn't had updates for a while.
We'd really like to have this feature to not only add/preserve a copyright header, but also a comment to warn developers that the file is auto generated and to not edit it.
Summary
Not sure if this is a bug or enhancement but It would be good if there was a way to preserve a copyright notice comment when doing d.ts rollup. I think it should probably do it by default but would be good to at least have the option. Currently I am having to patch the copyright notice back in after running the rollup.
Repro steps
Run API extractor targeting an entry point d.ts file which contains a copyright notice:
index.d.ts
Expected result: Copyright header is preserved
myPackage.d.ts
Actual result: Copyright header is removed
myPackage.d.ts
Details
Related links https://github.com/microsoft/TypeScript/issues/12307#issuecomment-311204590 https://github.com/microsoft/TypeScript/issues/4734 zulip thread
Standard questions
Please answer these questions to help us investigate your issue more quickly:
@microsoft/api-extractor
version?node -v
)?