Clarify transform-only parameter decorator contract

Author: jtenner

src/ast.ts

@@ -930,7 +930,7 @@ export class FunctionTypeNode extends TypeNode {
     super(NodeKind.FunctionType, isNullable, range);
   }
 
-  /** Decorators on an explicit `this` parameter, if any. */
+  /** Decorators on an explicit `this` parameter, if any, preserved for transforms. */
   explicitThisDecorators: DecoratorNode[] | null = null;
 }
 
@@ -977,7 +977,7 @@ export class ParameterNode extends Node {
     super(NodeKind.Parameter, range);
   }
 
-  /** Decorators, if any. */
+  /** Decorators, if any, preserved so transforms can rewrite them before validation. */
   decorators: DecoratorNode[] | null = null;
   /** Implicit field declaration, if applicable. */
   implicitFieldDeclaration: FieldDeclaration | null = null;

src/compiler.ts

@@ -536,6 +536,7 @@ export class Compiler extends DiagnosticEmitter {
 
     // initialize lookup maps, built-ins, imports, exports, etc.
     this.program.initialize();
+    // Reject any parameter decorators that transforms left on the AST.
     this.program.validateParameterDecorators();
 
 

src/parser.ts

@@ -698,12 +698,13 @@ export class Parser extends DiagnosticEmitter {
   // Indicates whether tryParseSignature determined that it is handling a Signature
   private tryParseSignatureIsSignature: bool = false;
 
-  /** Parses a function type, as used in type declarations. */
+  /** Parses a function type, preserving parameter decorators for transforms. */
   tryParseFunctionType(
     tn: Tokenizer
   ): FunctionTypeNode | null {
 
-    // at '(': ('...'? Identifier '?'? ':' Type (','  '...'? Identifier '?'? ':' Type)* )? ')' '=>' Type
+    // at '(': (Decorator* ('...'? Identifier '?'? ':' Type | this ':' Type)
+    //   (',' Decorator* ('...'? Identifier '?'? ':' Type | this ':' Type))* )? ')' '=>' Type
 
     let state = tn.mark();
     let startPos = tn.tokenPos;
@@ -937,6 +938,7 @@ export class Parser extends DiagnosticEmitter {
   private parseParameterDecorators(
     tn: Tokenizer
   ): DecoratorNode[] | null {
+    // Preserve parameter decorators in the AST so transforms can inspect or remove them later.
     let decorators: DecoratorNode[] | null = null;
     while (tn.skip(Token.At)) {
       let decorator = this.parseDecorator(tn);
@@ -1249,23 +1251,25 @@ export class Parser extends DiagnosticEmitter {
     return null;
   }
 
+  /** Explicit `this` parameter captured by the current parseParameters call, if any. */
   private parseParametersThis: NamedTypeNode | null = null;
+  /** Decorators on the explicit `this` parameter, preserved for transforms. */
   private parseParametersThisDecorators: DecoratorNode[] | null = null;
 
   parseParameters(
     tn: Tokenizer,
     isConstructor: bool = false
   ): ParameterNode[] | null {
 
-    // at '(': (Parameter (',' Parameter)*)? ')'
+    // at '(': (Decorator* Parameter (',' Decorator* Parameter)*)? ')'
 
     let parameters = new Array<ParameterNode>();
     let seenRest: ParameterNode | null = null;
     let seenOptional = false;
     let reportedRest = false;
     let thisType: TypeNode | null = null;
 
-    // check if there is a leading `this` parameter
+    // check if there is a leading `this` parameter, preserving any decorators on it
     this.parseParametersThis = null;
     this.parseParametersThisDecorators = null;
 
@@ -1361,7 +1365,8 @@ export class Parser extends DiagnosticEmitter {
     decorators: DecoratorNode[] | null = null
   ): ParameterNode | null {
 
-    // before: ('public' | 'private' | 'protected' | '...')? Identifier '?'? (':' Type)? ('=' Expression)?
+    // before: Decorator* ('public' | 'private' | 'protected' | 'readonly')? '...'? Identifier
+    //   '?'? (':' Type)? ('=' Expression)?
 
     let isRest = false;
     let isOptional = false;

src/program.ts

@@ -495,7 +495,7 @@ export class Program extends DiagnosticEmitter {
   nextSignatureId: i32 = 0;
   /** An indicator if the program has been initialized. */
   initialized: bool = false;
-  /** An indicator if parameter decorators have been validated. */
+  /** Indicates whether the one-shot post-transform parameter decorator validation has run. */
   parameterDecoratorsValidated: bool = false;
 
   // Lookup maps
@@ -1532,7 +1532,7 @@ export class Program extends DiagnosticEmitter {
     }
   }
 
-  /** Validates that no parameter decorators survive past transform time. */
+  /** Rejects parameter decorators that survive transform time. These remain transform-only syntax. */
   validateParameterDecorators(): void {
     if (this.parameterDecoratorsValidated) return;
     this.parameterDecoratorsValidated = true;