Generated diagnostics file doesn't explain its source.

[ghost]

Background:

The generate-diagnostics build step takes JSON-encoded diagnostics data and transforms it into TypeScript to define the Diagnostics object used throughout the compiler.

Problem:

The only indication that this has occurred is a comment at the top of the generated file that says // <auto-generated />, but neither the name of the JSON source file nor the name of file containing the code that has generated it (processDiagnosticsMessages.ts) are given. This can make it difficult to figure out the correct file to modify, especially if using a tool that jumps to the definition of a Diagnostics key. (Relevant: #3549.)

Proposed solution:

Include in the comments of the auto-generated file the name of both the generator and the name of the JSON input file it was generated from.

Does the <auto-generated /> element have any actual significance? I.e., is there a tool making use of it, or was it an ad-hoc way to indicate that the generated file should not be modified? Could we encode these file names as attributes on this element?

[RyanCavanaugh]

This is just a mimic of C# auto-generated files; there's no implication for tools (just humans). It'd be fine to put some more complex message up there.

[CyrusNajmabadi]

It’s a general convention for how auto-generated files are marked. If you want to add additional information, it would be preferred if you could do it in a comment provided after this line.

   -- Cyrus

From: Ryan Cavanaugh [mailto:notifications@github.com]
Sent: Sunday, June 21, 2015 7:21 PM
To: Microsoft/TypeScript
Subject: Re: [TypeScript] Generated diagnostics file doesn't explain its source. (#3591)

This is just a mimic of C# auto-generated files; there's no implication for tools (just humans). It'd be fine to put some more complex message up there.

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/3591#issuecomment-113982748.