Update the specification section about metadata (#3787)

The association that binds each metadatum in a Dart program to a language construct is specified in a way that is somewhat inconsistent with the grammar. For example, it associates the metadata declared in front of a `<libraryName>` with the keyword `library`, not with the library name directive as a whole.

This PR changes the wording such that metadata which occurs at the beginning of a grammar rule is associated with the construct as a whole. If the metadata occurs in any other location in the rule then we continue to use the rule which is specified prior to this PR: The metadata is associated with the program construct which is derived from the following non-terminal. The latter rule works well with cases like `<classDeclaration> ::= ... (<metadata> <classMemberDeclaration>)* ...`.

This PR also adds a small amount of rationale text, saying that this whole topic has an implementation specific element, and the normative rules are intentionally somewhat flexible. We trust all tool maintainers to maintain a reasonable amount of consistency, and provide just a few normative rules in order to make it easier to be consistent, insofar as this is possible with the given program representation.

Author: eernstg

specification/dartLangSpec.tex

@@ -8304,16 +8304,43 @@ \section{Metadata}
 }
 
 \LMHash{}%
-Metadata is associated with the abstract syntax tree
-of the program construct $p$ that immediately follows the metadata,
-and which is not itself metadata or a comment.
+Metadata that occurs as the first element of
+the right hand side of a grammar rule
+is associated with the abstract syntax tree for the non-terminal
+on the left hand side of said grammar rule
+\commentary{(that is, it is associated with its parent)}.
+Otherwise, metadata is associated with the abstract syntax tree
+of the program construct $p$ that immediately follows the metadata
+in the grammar rule.
+
+\rationale{%
+These rules are intended to ensure a minimal level of consistency
+in the association that binds each metadatum to a program construct.
+The structure of the abstract syntax tree is implementation specific,
+and it is not even guaranteed that a tool will use anything
+which is known as an abstract syntax tree.
+In that case the phrase `abstract syntax tree' should be interpreted as
+the program representation entities which are actually used.
+
+This implies that the fine details of the association between metadata
+and an abstract syntax tree node is also implementation specific.
+In particular, an implementation can choose to associate a given metadatum
+with more than one abstract syntax tree node.%
+}
+
+\LMHash{}%
 Metadata can be retrieved at run time via a reflective call,
 provided the annotated program construct $p$ is accessible via reflection.
 
 \commentary{%
 Obviously, metadata can also be retrieved statically by
 parsing the program and evaluating the constants via a suitable interpreter.
-In fact, many if not most uses of metadata are entirely static.%
+In fact, many if not most uses of metadata are entirely static.
+In this case the binding of each metadatum to an abstract syntax tree node
+is determined by the given static analysis tool,
+which is of course not subject to any constraints in this document.
+Surely it will still be useful to strive for consistency among all tools
+with respect to the binding from metadata to abstract syntax tree nodes.%
 }
 
 \rationale{%
@@ -18189,8 +18216,10 @@ \subsection{For}
 <forStatement> ::= \AWAIT? \FOR{} `(' <forLoopParts> `)' <statement>
 
 <forLoopParts> ::= <forInitializerStatement> <expression>? `;' <expressionList>?
-  \alt <metadata> <declaredIdentifier> \IN{} <expression>
-  \alt <identifier> \IN{} <expression>
+  \alt <forInLoopPrefix> \IN{} <expression>
+
+<forInLoopPrefix> ::= <metadata> <declaredIdentifier>
+  \alt <identifier>
 
 <forInitializerStatement> ::= <localVariableDeclaration>
   \alt <expression>? `;'