diff --git a/FAQ.md b/FAQ.md index cd9d3d85..911ed8ec 100644 --- a/FAQ.md +++ b/FAQ.md @@ -68,9 +68,13 @@ - [Why is a file in the `exclude` list still picked up by the compiler?](#why-is-a-file-in-the-exclude-list-still-picked-up-by-the-compiler) - [How can I specify an `include`?](#how-can-i-specify-an-include) - [Why am I getting the `error TS5055: Cannot write file 'xxx.js' because it would overwrite input file.` when using JavaScript files?](#why-am-i-getting-the-error-ts5055-cannot-write-file-xxxjs-because-it-would-overwrite-input-file-when-using-javascript-files) + - [Comments](#comments) + - [Why some comments are not preserved in emitted JavaScript even when `--removeComments` is not specified?](#why-some-comments-are-not-preserved-in-emitted-javascript-even-when---removecomments-is-not-specified) + - [Why Copyright comments are removed when `--removeComments` is true?](#why-copyright-comments-are-removed-when---removecomments-is-true) - [Glossary and Terms in this FAQ](#glossary-and-terms-in-this-faq) - [Dogs, Cats, and Animals, Oh My](#dogs-cats-and-animals-oh-my) - ["Substitutability"](#substitutability) + - [Trailing, leading, and detached comments](#trailing-leading-and-detached-comments) - [GitHub Process Questions](#github-process-questions) - [What do the labels on these issues mean?](#what-do-the-labels-on-these-issues-mean) - [I disagree with the outcome of this suggestion](#i-disagree-with-the-outcome-of-this-suggestion) @@ -1327,6 +1331,43 @@ If you don't want JavaScript files included in your project at all, simply set t If you do want to include and compile these JavaScript files, set the `outDir` option or `outFile` option to direct the emitted files elsewhere, so they won't conflict with your source files; If you just want to include the JavaScript files for editing and don't need to compile, set the `noEmit` compiler option to `true` to skip the emitting check. +## Comments + +### Why some comments are not preserved in emitted JavaScript even when `--removeComments` is not specified? + +TypeScript compiler uses a position of a node in the abstract syntax tree to retrieve its comments during emit. +Because, the compiler does not store all tokens into the tree, some comments may be missed in an output JavaScript file. +For example, we do not store following tokens into the tree `,`, `{`, `}`, `(`, `)`. +Therefore, trailing comments or leading comments of such token cannot be retrieved during emit. +At the moment, there is not an easy method to preserve such comments without storing those tokens. +Doing so, however, can significantly increase the tree size and potentially have performance impact. + +Some cases where TypeScript compiler will not be able to preserve your comments: + +```ts +/* comment */ +