Inconsistent behavior of beginToken for some analyzer AST nodes with doc comments

[stereotype441]

The following analyzer AST node kinds support a documentationComment getter:

• AugmentationImportDirective
• ClassDeclaration
• ClassTypeAlias
• ConstructorDeclaration
• DeclaredIdentifier
• EnumConstantDeclaration
• EnumDeclaration
• ExportDirective
• ExtensionDeclaration
• ExtensionTypeDeclaration
• FieldDeclaration
• FieldFormalParameter
• FunctionDeclaration
• FunctionTypeAlias
• FunctionTypedFormalParameter
• GenericTypeAlias
• ImportDirective
• LibraryAugmentationDirective
• LibraryDirective
• MethodDeclaration
• MixinDeclaration
• PartDirective
• PartOfDirective
• PatternVariableDeclaration
• SimpleFormalParameter
• SuperFormalParameter
• TopLevelVariableDeclaration
• TypeParameter
• VariableDeclaration
• VariableDeclarationList

For nearly all of these node kinds, if the documentationComment is non-null, and the documentation comment precedes the first annotation, the beginToken getter returns the first token of the documentation comment. This is consistent with the behavior of the visitChildren method, which visits any annotations as well as the documentation comment (if present), in source order, prior to visiting the remaining children of the node.

However, for these 4 node kinds, beginToken always returns the first non-comment token of the declaration, ignoring the documentationComment:

• FieldFormalParameter
• FunctionTypedFormalParameter
• SimpleFormalParameter
• SuperFormalParameter

But visitChildren still visits the documentation comment (if present), so visitChildren and beginToken behave inconsistently for these 4 node kinds.

[stereotype441]

I'm currently investigating how difficult it would be to change the behavior of beginToken for the 4 "...FormalParameter" kinds so that it's consistent with the behavior of the other AST node kinds. Unfortunately, it's not a trivial change; the formatter appears to rely on the current (inconsistent) behavior.

I'll try to update this issue when I have a clearer view of the situation.