WIP/RFC - first jab at implementing Flow-style annotations-in-comments

[akdor1154]

See #9694 .

My workplace, and many community projects, are aware of the analysis capabilities of Typescript, but shy away from having a build step added to projects that are currently written in raw JS. This makes Typescript a non-starter. Facebook's Flow has a nifty feature whereby annotations can be added as comments inline in JS, meaning no build step is required. E.g.

const s /*: string */ = 'asdf';

function f(s /*: string */) /*: number */ {
    return 4;
}

/*::
interface MyObject {
    s: string;
    n: number;
}
*/
const o /*: MyObject */ = {s: 'asdf', n: 123}

This seems to have seen wide approval and support from the Flow community.

This PR implements this feature in Typescript. It's clearly uglier that direct annotations, but it's a much more succinct way of adding Typescript annotations to valid Javascript than JSDoc.

Two constructs are supported. /*: typename*/ is interpreted as : typename, as in the first two examples above. /* :: statements; ... */ is interpreted as statements; ....

It may also be worth considering /* <parameter> */ -> <parameter> to allow manually specifying generic parameters where elision is not possible. This would also allow angle bracket type assertions. Note that this would be a convenience extension - as currently implemented, this is already possible with /* :: <parameter> */

This is a first go to see how easy this was to implement - I am aware that the CLA needs to be signed, test cases need to be written, that the issue needs to be tagged as needing a proposal (and that there is no guarantee this will happen!), and said proposal needs to be written and accepted, and that this is a language change and will thus be either highly contentious or rejected outright.

[msftclas]

Hi @akdor1154, I'm your friendly neighborhood Microsoft Pull Request Bot (You can call me MSBOT). Thanks for your contribution!

In order for us to evaluate and accept your PR, we ask that you sign a contribution license agreement. It's all electronic and will take just minutes. I promise there's no faxing. https://cla.microsoft.com.

TTYL, MSBOT;

[pardonmyenglish]

Two constructs are supported. /*: typename*/ is interpreted as : typename, as in the first two examples above. /* :: statements; ... */ is interpreted as statements; ....

I assume you mean /*:: statements; ... */ (no space between the asterisk and colons)

[akdor1154]

Sort of - parsing is tolerant of whitespace, matching /*:..., /* :..., /* :..., etc.

[mhegazy]

Please see https://github.com/Microsoft/TypeScript/wiki/Type-Checking-JavaScript-Files for relevant information.

[akdor1154]

:( Though I really appreciate the thorough JSDoc support, I find Typescript's native type expressions to be far more legible.
There are things that are far easier to express in Typescript's type system than in JSDoc (i.e. interfaces' interplay with discriminators and type-guards). I hope the team revisits this one day.