microsoft / TypeScript-Handbook

Deprecated, please use the TypeScript-Website repo instead
https://github.com/microsoft/TypeScript-Website
Apache License 2.0
4.88k stars 1.13k forks source link

Add a page (or pages) with a list of keywords, and links to documentation #341

Open zspitz opened 8 years ago

zspitz commented 8 years ago

Such a list would make it easier for users to get and retain a fuller grasp of Typescript, by having an overview of the syntax of the language, and by clearly differentiating the parts that are common to ES5/6/7 and the parts that are unique to Typescript.

Presenting this information in this way, would allow users to reduce the question of "What does this keyword do in Typescript?", to "What does this keyword do differently in Typescript than in Javascript?".

There is something similar on MDN, but I think the format of the Javascript statment list on MSDN, with a one-line description for each keyword, is better:

Keyword Definition
const Force the use of const enums

(The MDN list is actually a single page describing the entire JS grammer -- whitespace, comments, operators, and literals -- but there is no point in describing these behaviors because whitespace, comments etc. are exactly the same as in Typescript. The only major area of difference is in the keywords.)

For the usages which Typescript shares with Javascript, I'm not sure which would be better -- not to mention them (this is a Typescript reference, not a Javascript reference), or link to authoritative sources of Javascript documentation (MDN and/or MSDN):

Keyword Language Definition
const JS MDN
TS Force the use of const enums (Spec)
var JS MDN MSDN
mhegazy commented 8 years ago

Most of the content is available. so if you would be willing to start the page would happily take the PR.

zspitz commented 8 years ago

Microsoft/TypeScript#2536 - issue regarding the spec.

zspitz commented 8 years ago

@mhegazy I've created a PR. There are a few keywords which I am unsure of their meaning / context:

and there are a few for which I couldn't find documentation in the Handbook: