1

Closed

Comments not preserved by TypeScript Compiler

description

Comments are not being preserved by the TypeScript compiler when ambient declarations or interfaces are present in the file. If you look at the enclosed zip you will find 4 files:
  • CommentsNotPreserved.ts - a TypeScript file with an ambient declaration and an interface included
// @reference ~/bundles/core

/// <reference path="../../../../typings/jquery/jquery.d.ts" />

declare var RandomDeclare: any;

interface RandomInterface {
    Anything: number;
}

/*!
 * Initialise the page
 */
$(document).ready(function () {

    // Nothing to see here, move along
});
  • CommentsNotPreserved.js - the compiled output with "//" comments removed and only "/ /" comments preserved
/*!
* Initialise the page
*/
$(document).ready(function () {
});
  • CommentsPreserved.ts - the same as CommentsNotPreserved.ts but with ambient declaration and interface removed
// @reference ~/bundles/core

/// <reference path="../../../../typings/jquery/jquery.d.ts" />

/*!
 * Initialise the page
 */
$(document).ready(function () {

    // Nothing to see here, move along
});
  • CommentsPreserved.js - the compiled output with most "//" comments preserved (with one exception inside the $(document).ready
// @reference ~/bundles/core
/// <reference path="../../../../typings/jquery/jquery.d.ts" />
/*!
* Initialise the page
*/
$(document).ready(function () {
});

I've been able to get around this by moving comments that I absolutely need (eg "// @reference " comments which are necessary as I am using Cassette's Asset Referencing) until after the ambient declarations / interfaces. Then the comments are preserved.

This seems a little on the quirky side though and it would be good if it could be addressed. I have noticed comments also being stripped in other circumstances as well but I don't have repro details to hand right now.

file attachments

Closed Jul 12, 2013 at 12:52 AM by danquirk
This is by design. The compiler chooses which comments to preserve and where to place them in the resulting JavaScript based on which Typescript constructs they are associated with. For ambient declarations and interfaces they're attached to a piece of Typescript which is not going to be emitted so the comment is not either. More than likely your comments for elements of this type are going to describe what they're for, but now the JavaScript would have a bunch of free floating comments describing types and variables which are not present.

comments

johnny_reilly wrote Jul 10, 2013 at 11:56 AM

By the way, you can demo the above issue in the TypeScript Playground.

johnny_reilly wrote Jul 12, 2013 at 9:18 AM

Thanks for responding @danquirk

I think I understand the logic behind that. Essentially the rule that should be followed could be stated as: If you want a comment preserved then don't place it before an ambient declaration or interface.

I'll definitely bear this in mind as I'm structuring my TS from now on. Is this documented anywhere that I could refer back to? I've had a quick look at the spec but don't see any mention of this. If there is something to refer to then it might prevent me raising non-issues in future.

By the way, this behaviour may have some bearing on your comment of May 17 at 12:01 AM on https://typescript.codeplex.com/workitem/995 : "At the moment we don't intend to change the behavior here because some users rely on the /// reference being present in the JavaScript for some post processing by other tools."

Effectively the presence of an ambient declaration or interface after the /// reference comments will strip them from the compiled JavaScript which will impact those other users that you mention. Maybe they're already aware of this behaviour but if not then perhaps they could be informed.

All the best,
John

danquirk wrote Aug 13, 2013 at 7:27 PM

Thanks John, I opened a new work item here (https://typescript.codeplex.com/workitem/1507) to cover the last issue you mention. We have a more robust model for comment preservation that we hope to implement in the future but for now we've been doing targeted fixes where comment preservation issues crop up in impactful ways and this may be one.

In the future do log a new issue or post in the discussion section if you find other issues after we've closed one like this (assuming they're unrelated, otherwise you could re-open a closed bug). We'll notice it much faster as you can tell from this highly delayed comment :)

johnny_reilly wrote Aug 14, 2013 at 8:32 AM

Will do Dan - thanks!