search

microsoft / TypeScript

TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
https://www.typescriptlang.org
Apache License 2.0
100.17k stars 12.38k forks source link

Include new features in handbook instead of referencing "What's new". #36009

Open Jeansen opened 4 years ago

Jeansen commented 4 years ago

While reading through the handbook I find something like this:

"From TypeScript 3.7 and onwards, you can use optional chaining to simplify working with nullable types." Where "optional chaining" links to the "What's new" page for version 3.7.

Why not include this in the handbook but put references - in the handbook - to other pages explaining "What's new"?

Please include all features of the language in the handbook. Actually I'd suggest to always update the handbook and only put references in the "What's new" page with a link to the relevant pages in the handbook.

RyanCavanaugh commented 4 years ago

We just haven't done the work yet

orta commented 4 years ago

I did this intentionally. There's a tension here because ?. is purely a JS language feature. It affects code flow, but so does an if statement and we leave documenting the runtime semantics of that to MDN also.

I think even in the new handbook we probably wouldn't be documenting it in any depth. Perhaps there's a space to say what versions of ECMAScript TypeScript is up to, and what the proposals we've implemented look like, but the TS docs need to focus on the extra layer TS adds and not the many layers of JS underneath.