Add documentation to AST and ASR asdl files

grammar/ASR.asdl

@@ -1,9 +1,18 @@
 -- Abstract Semantic Representation (ASR) definition
 
--- The aim of ASR is to represent all semantics in a non-redundant way,
--- and that has all the information available locally, so that the backend
--- can do a single pass over ASR and have all the information at hand to
--- generate code.
+-- The aim of ASR is to represent all semantics in a non-redundant way, and that
+-- has all the semantic information available locally, so that the backend can
+-- do a single pass over ASR and have all the information at hand to generate
+-- code.
+--
+-- ASR is always semantically valid Fortran code. It is as far from the original
+-- Fortran language code as possible (i.e. everthing is explicitly figured out,
+-- all semantic information gathered and readily available locally from each ASR
+-- node), while ensuring no semantic information was lost (no lowering was
+-- done), so one can still generate Fortran code from ASR that will be logically
+-- equivalent to the original code.
+--
+-- ASR can be used to do Fortran level transformations (such as optimizations).
 
 -- ASDL's builtin types are:
 --   * identifier

grammar/AST.asdl

@@ -20,6 +20,12 @@
 -- Specific tools may choose to produce language interfaces that represent
 -- these types and the ASDL tree in a language specific way (e.g. use finite
 -- precision integers and signal an error otherwise).
+--
+-- At the AST level we strictly only represent local syntax (no semantics). That
+-- way each syntax construct is parsed locally, no need to do any non-local
+-- lookups to figure out what AST node to construct. That is the job of the AST
+-- to ASR conversion to do non-local lookups to figure out what is what (i.e.,
+-- disambiguate) and report any errors.
 
 module AST {