📝 grammar contributing docs 🌹

Author: basarat

docs/grammar.md

@@ -1,11 +1,20 @@
-# CSON Grammar
+# CSON grammar
+
+Atom works with a CSON grammar. We generate this from Microsoft supported grammar files. This is the code https://github.com/TypeStrong/atom-typescript/blob/master/scripts/grammar.js run using `npm run build` that updates our grammar file.
+
+For grammar issues go here : https://github.com/Microsoft/TypeScript-TmLanguage/issues and link back to us if you want us to pull from upstream :rose:.
+
+# CSON Grammar Docs
 What is meant by `name` and `captures`
 https://discuss.atom.io/t/grammar-understanding-captures-vs-name/14783
 
 Generally the best docs:
 http://manual.macromates.com/en/language_grammars.html
 
 # Dynamic Grammar
+
+> Warning : :warning: This feature is now legacy but has some good learning
+
 We used dynamic (code driven) grammar initially. Following are the lessons still worth sharing but we are using the CSON grammar now.
 
 I am using `atom` and `first-mate` interchangeably here. There isn't a documented way of creating a grammar from *code*. We found a hacky way by reading a *lot of source code*. Please look at `typeScriptGrammar.ts`. Basically you inherit from `Grammar` and let that do the heavy lifting. Then all you need is to return `AtomTokens` from `tokenizeLine`. The way the atom grammar works is that they will store the returned `ruleSet` for any line and call `tokenizeLine` for the next line passing in that `ruleSet`. As soon as you edit a line all the following lines are invalidated and  `tokenizeLine` is called for them again. This works beautifully with the `ts.createClassifier` which is a quick syntactic classifier provided by the TS language service. It only depends on a `finalLexState` (e.g. did the previous line have a continuing multiline comment) and that is what we store in the `ruleSet`.