add macro keyword (#2008)

Author: jakemac53

analysis_options.yaml

@@ -1,3 +1,5 @@
 analyzer:
   exclude:
     - accepted/2.3/spread-collections/examples/**
+    # Uses not-yet-existing language features
+    - working/macros/example/**

working/macros/example/data_class.dart

@@ -5,7 +5,7 @@ import '../api/code.dart';
 
 const dataClass = _DataClass();
 
-class _DataClass implements ClassDeclarationsMacro, ClassDefinitionMacro {
+macro class _DataClass implements ClassDeclarationsMacro, ClassDefinitionMacro {
   const _DataClass();
 
   @override
@@ -29,7 +29,7 @@ class _DataClass implements ClassDeclarationsMacro, ClassDefinitionMacro {
 
 const autoConstructor = _AutoConstructor();
 
-class _AutoConstructor implements ClassDeclarationsMacro {
+macro class _AutoConstructor implements ClassDeclarationsMacro {
   const _AutoConstructor();
 
   @override
@@ -108,7 +108,7 @@ class _AutoConstructor implements ClassDeclarationsMacro {
 const copyWith = _CopyWith();
 
 // TODO: How to deal with overriding nullable fields to `null`?
-class _CopyWith implements ClassDeclarationsMacro {
+macro class _CopyWith implements ClassDeclarationsMacro {
   const _CopyWith();
 
   @override
@@ -146,7 +146,7 @@ class _CopyWith implements ClassDeclarationsMacro {
 
 const hashCode = _HashCode();
 
-class _HashCode implements ClassDeclarationsMacro, ClassDefinitionMacro {
+macro class _HashCode implements ClassDeclarationsMacro, ClassDefinitionMacro {
   const _HashCode();
 
   @override
@@ -175,7 +175,7 @@ external int get hashCode;'''));
 
 const equality = _Equality();
 
-class _Equality implements ClassDeclarationsMacro, ClassDefinitionMacro {
+macro class _Equality implements ClassDeclarationsMacro, ClassDefinitionMacro {
   const _Equality();
 
   @override
@@ -204,7 +204,7 @@ external bool operator==(Object other);'''));
 
 const toString = _ToString();
 
-class _ToString implements ClassDeclarationsMacro, ClassDefinitionMacro {
+macro class _ToString implements ClassDeclarationsMacro, ClassDefinitionMacro {
   const _ToString();
 
   @override

working/macros/feature-specification.md

@@ -293,17 +293,32 @@ introspection APIs. These macros can fully introspect on any type reachable from
 the declarations they are applied to, including introspecting on members of
 classes, etc.
 
-## Macro definitions
+## Macro declarations
 
-Macro definitions do not have any unique syntax or language features. They are
-regular Dart class declarations. They are macros by virtue of the fact that they
-implement one or more special "macro" interfaces defined by the Dart core
-libraries.
+Macros are a special type of class, which are preceded by the `macro` keyword,
+and have some additional limitations that classes don't have.
 
-*Note: The API is still being designed, and lives [here][api].*
+This keyword allows compilers (and users) to identify macros at a glance,
+without having to check the type hierarchy to see if they implement `Macro`.
+
+See some example macros [here][examples].
+
+[examples]: https://github.com/dart-lang/language/tree/master/working/macros/example
+
+### Macro limitations/requirements
+
+-  All macro constructors must be marked as const.
+-  See the [Macro Arguments](#Macro-arguments) section to understand how macro
+constructors are invoked, and their limitations.
+-  All macros must implement at least one of the `Macro` interfaces.
+-  Macros cannot be abstract.
+
+*Note: The Macro API is still being designed, and lives [here][api].*
 
 [api]: https://github.com/dart-lang/language/blob/master/working/macros/api
 
+### Writing a Macro
+
 Every macro interface is a subtype of a root [Macro][] [marker interface][].
 There are interfaces for each kind of declaration macros can be applied to:
 class, function, etc. Then, for each of those, there is an interface for each