Comments

grammar/src/attributes.grm

@@ -2,14 +2,14 @@
 h2. Annotations
 */
 
-attributes
-  : attributeAnnotation*
+annotations
+  : annotation*
   ;
 
-attributeAnnotation
-  : "[" attribute{","} "]"
+annotation
+  : "[" annotationEntry{","} "]"
   ;
 
-attribute
+annotationEntry
   : SimpleName{"."} (valueArguments | "=" expression)?
   ;

grammar/src/class.grm

@@ -1,7 +1,7 @@
 /**
 h2. Classes
 
-*Relevant pages:* [Classes and Inheritance]
+bq. See [Classes and Inheritance]
 */
 
 /*
@@ -20,16 +20,11 @@ class
   : modifiers "class" SimpleName
       typeParameters?
       ("wraps" valueParameters? | modifiers valueParameters?)?
-      (":" attributes delegationSpecifier{","})?
+      (":" annotations delegationSpecifier{","})?
       (classBody? | enumClassBody)
   ;
 
 
-typeParameters
-  : "<" typeParameter{","} ">"
-    ("where" typeConstraint{","})?
-  ;
-
 classBody
   : ("{" memberDeclaration "}")?
   ;
@@ -43,11 +38,23 @@ explicitDelegation
   : userType "by" expression // internal this expression no foo {bar} is allowed
   ;
 
+typeParameters
+  : "<" typeParameter{","} ">"
+    ("where" typeConstraint{","})?
+  ;
+
 typeParameter
   : modifiers SimpleName (":" userType)?
   ;
 
+/**
+bq. See [Generic classes|Generics#Generic classes]
+*/
+
 typeConstraint
-  : attributes SimpleName ":" type
-  : attributes "class" "object" SimpleName ":" type
-  ;
+  : annotations SimpleName ":" type
+  : annotations "class" "object" SimpleName ":" type
+  ;
+/**
+bq. See [Generic constraints|Generics#Generic constraints]
+*/

grammar/src/class_members.grm

@@ -53,7 +53,11 @@ anonymousInitializer
 classObject
   : modifiers "class" object
   ;
+/**
+bq. See [Class objects|Classes and Inheritance#Class objects]
+*/
 
+[undocumented]
 constructor
   : modifiers "this" valueParameters (":" initializer{","}) block?
   ;
@@ -67,8 +71,8 @@ functionParameter
   ;
 
 initializer
-  : attributes "this" valueArguments
-  : attributes constructorInvocation // type parameters may (must?) be omitted
+  : annotations "this" valueArguments
+  : annotations constructorInvocation // type parameters may (must?) be omitted
   ;
 
 block
@@ -77,7 +81,7 @@ block
 
 function
   : modifiers "fun" typeParameters?
-      (type "." | attributes/*for receiver type*/)?
+      (type "." | annotations/*for receiver type*/)?
       SimpleName
       typeParameters? valueParameters (":" type)?
       functionBody?
@@ -90,11 +94,14 @@ functionBody
 
 property
   : modifiers ("val" | "var")
-      typeParameters? (type "." | attributes)?
+      typeParameters? (type "." | annotations)?
       SimpleName (":" type)?
       ("=" expression SEMI?)?
       (getter? setter? | setter? getter?) SEMI?
   ;
+/**
+bq. See [Properties and Fields]
+*/
 
 getter
   : modifiers "get"
@@ -111,4 +118,7 @@ parameter
   ;
 
 object
-  : "object" SimpleName ":" ":" delegationSpecifier{","}? classBody? // Class body can be optional: this is a declaration
+  : "object" SimpleName ":" delegationSpecifier{","}? classBody? // Class body can be optional: this is a declaration
+/**
+bq. See [Object expressions and Declarations]
+*/

grammar/src/control.grm

@@ -1,5 +1,7 @@
 /**
 h3. Control structures
+
+bq. See [Control structures]
 */
 
 if
@@ -11,7 +13,7 @@ try
   ;
 
 catchBlock
-  : "catch" "(" attributes SimpleName ":" userType ")" block
+  : "catch" "(" annotations SimpleName ":" userType ")" block
   ;
 
 finallyBlock
@@ -25,7 +27,7 @@ loop
   ;
 
 for
-  : "for" "(" attributes ("val" | "var")? SimpleName (":" type)? "in" expression ")" expression
+  : "for" "(" annotations ("val" | "var")? SimpleName (":" type)? "in" expression ")" expression
   ;
 
 while

grammar/src/enum.grm

@@ -1,5 +1,7 @@
 /**
 h3. Enum classes
+
+bq. See [Enum classes]
 */
 
 enumClassBody

grammar/src/expressions.grm

@@ -1,6 +1,8 @@
 /**
 h2. Expressions
 
+bq. See [Expressions]
+
 h3. Precedence
 
 ||*Precedence*||Title||Symbols||
@@ -198,7 +200,7 @@ prefixUnaryOperation
   : "-" : "+"
   : "++" : "--"
   : "!"  // No ~
-  : attributes // mandatory
+  : annotations // mandatory
   : label
   ;
 

grammar/src/lexical.grm

@@ -7,14 +7,14 @@ Digit
   : ["0".."9"];
 
 IntegerLiteral
-  : Digit+ "L"?
+  : Digit+?
 
 FloatLiteral
   : <java double literal>;
 
 [helper]
 HexDigit
-  : Digit | ["A"-"F", "a"-"f"];
+  : Digit | ["A".."F", "a".."f"];
 
 HexadecimalLiteral
   : "0x" HexDigit+;

grammar/src/modifiers.grm

@@ -12,7 +12,7 @@ modifier
   : varianceAnnotation
   : memberModifier
   : parameterKind
-  : attributes
+  : annotations
   ;
 
 classModifier

grammar/src/notation.grm

@@ -17,5 +17,5 @@ Operator {color:blue}*|*{color} denotes _alternative_
 Operator {color:blue}*\**{color} denotes _iteration_ (zero or more)
 Operator {color:blue}*+*{color} denotes _iteration_ (one or one)
 Operator {color:blue}*?*{color} denotes _option_ (zero or one)
-alpha{color:blue}*{*{color}beta{color:blue}*}*{color} denotes a nonempty _beta_-separated list of _alpha_s
+alpha{color:blue}*{*{color}beta{color:blue}*}*{color} denotes a nonempty _beta_-separated list of _alpha_'s
 */

grammar/src/toplevel.grm

@@ -27,14 +27,18 @@ import
   : "import" ("namespace" ".")? SimpleName{"."} ("." "*" | "as" SimpleName)? SEMI?
   ;
 
+/**
+bq. See [Imports|Namespaces#Imports]
+*/
+
 toplevelObject
   : namespace
   : class
   : object
-  : extension
   : function
   : property
   : typedef
+  : extension
   ;
 
 namespace
@@ -44,10 +48,16 @@ namespace
     "}"
   ;
 
+/**
+bq. See [Namespaces]
+*/
+
+[undocumented]
 typedef
   : modifiers "type" SimpleName typeParameters? "=" type
   ;
 
+[undocumented]
 extension
   : modifiers "extension" SimpleName? typeParameters? "for" type classBody? // properties cannot be lazy, cannot have backing fields
   ;

grammar/src/types.grm

@@ -1,5 +1,7 @@
 /**
 h2. Types
+
+bq. See [Types]
 */
 
 /*
@@ -14,7 +16,7 @@ Foo<Bar<X>, T, Object> // user type
 */
 
 type
-  : attributes typeDescriptor
+  : annotations typeDescriptor
 
 // IF YOU CHANGE THIS, please, update TYPE_FIRST in JetParsing
 typeDescriptor

grammar/src/when.grm

@@ -1,7 +1,7 @@
 /**
 h4. Pattern matching
 
-*Relevant pages:* [Pattern matching]
+bq. See [Pattern matching]
 */
 
 when
@@ -28,7 +28,7 @@ whenCondition
   ;
 
 pattern
-  : attributes pattern
+  : annotations pattern
   : type // '[a] T' is a type-pattern 'T' with an attribute '[a]', not a type-pattern '[a] T'
          // this makes sense because is-check may be different for a type with attributes
   : tuplePattern