Skip to content

Commit 280173c

Browse files
committed
incorporate reviews
1 parent 5629f0f commit 280173c

File tree

1 file changed

+28
-18
lines changed

1 file changed

+28
-18
lines changed

src/content/language/macros.md

+28-18
Original file line numberDiff line numberDiff line change
@@ -8,10 +8,10 @@ description: Learn about the experimental macros feature as it develops.
88
[static meta-programming][motivation] to the Dart language.
99

1010
A Dart macro is a user-defineable piece of code that takes in other code as parameters
11-
and operates on it during compile time to create, modify, or add declarations.
11+
and operates on it in real-time to create, modify, or add declarations.
1212

1313
You can think about the macro system in two parts: using macros and writing macros.
14-
This page covers each (at a high level, as ***the feature is still under development***)
14+
This page covers each (at a high level, as ***the feature is still in preview***)
1515
in the following sections:
1616

1717
- [**The `JsonCodable` macro**](#the-jsoncodable-macro):
@@ -22,7 +22,8 @@ common issue of tedious JSON serialization in Dart.
2222
- [**The macros feature in general**](#the-macros-language-feature):
2323
Why we're adding macros to Dart, motivating use cases,
2424
benefits over existing code gen solutions,
25-
and a cursory overview of how writing macros works.
25+
and a cursory overview of how writing macros will work in the future once
26+
the feature is complete.
2627

2728
[spec]: {{site.repo.dart.lang}}/blob/main/working/macros/feature-specification.md
2829
[motivation]: {{site.repo.dart.lang}}/language/blob/main/working/macros/motivation.md
@@ -31,6 +32,8 @@ and a cursory overview of how writing macros works.
3132

3233
:::important
3334
The `JsonCodable` macro is not stable and currently behind an [experiment flag][].
35+
It only works with the [dev channel][channel] releases of Dart 3.5.0 and later.
36+
3437
Functionality is subject to change.
3538
:::
3639

@@ -41,37 +44,40 @@ and a `fromJson` deserialization constructor.
4144

4245
[experiment flag]: /tools/experiment-flags
4346
[`JsonCodable`]: {{site.repo.dart.sdk}}/tree/main/pkg/json
47+
[channel]: /get-dart/#release-channels
4448

4549
### Set up the experiment
4650

47-
1. [Add the package][] to your pubspec and retrieve
51+
1. Switch to the [dev channel][channel] and upgrade to at least 3.5.0.
52+
53+
2. [Add the package][] to your pubspec and retrieve
4854
its dependencies.
49-
2. [Add the experiment][] to the `analysis_options.yaml`
55+
3. [Add the experiment][] to the `analysis_options.yaml`
5056
file at the root of your project:
5157

5258
```yaml
5359
analyzer:
5460
enable-experiment:
5561
- macros
5662
```
57-
3. Import it in the file you plan to use it:
63+
4. Import it in the file you plan to use it:
5864
59-
```dart
60-
import 'package:json/json.dart';
61-
```
65+
```dart
66+
import 'package:json/json.dart';
67+
```
6268

63-
4. Run your project with the experiment flag:
69+
5. Run your project with the experiment flag:
6470

65-
```console
66-
dart --enable-experiment=macros run bin/my_app.dart
67-
```
71+
```console
72+
dart --enable-experiment=macros run bin/my_app.dart
73+
```
6874

6975
[Add the package]: /guides/packages
7076
[Add the experiment]: /tools/experiment-flags#using-experiment-flags-with-the-dart-analyzer-command-line-and-ide
7177

7278
### Use the macro
7379

74-
To use the `JsonCodable` macro, append the annotation to the class you want to serialize:
80+
To use the `JsonCodable` macro, attach the annotation to the class you want to serialize:
7581

7682
```dart
7783
import 'package:json/json.dart';
@@ -108,7 +114,9 @@ void main() {
108114

109115
### View the generated code
110116

111-
You can optionally view the generated code.
117+
Sometimes it can be useful to view the generated code to better understand
118+
how a macros works, or to inspect the details of what it offers.
119+
112120
Click on the "**Go to Augmentation**" link that appears under the annotation
113121
in your IDE (supported in VSCode and IntelliJ)
114122
to see how the macro generates `toJson` and `fromJson`.
@@ -149,11 +157,12 @@ treatment of null and generics, and more, check out [the README][].
149157

150158
Dart macros are a *static* metaprogramming, or code generation, solution.
151159
Unlike *runtime* code generation solutions (like [build_runner][]),
152-
macros are fully integrated into the Dart language and executed by the compiler.
160+
macros are fully integrated into the Dart language
161+
and executed automatically in the background by Dart tools.
153162
This makes macros much more efficient than relying on an secondary tool:
154163

155164
- **Nothing extra to run**;
156-
simply call `dart ` / `flutter run <your app>` and the macro builds with your code.
165+
macros build in real-time as you write your code.
157166
- **No duplicated work** or constant recompiling hurting performance;
158167
all the building and code generation happen directly in the compiler,
159168
automatically.
@@ -166,12 +175,14 @@ This makes macros much more efficient than relying on an secondary tool:
166175
And also far more efficient, and far less error prone, than manually
167176
writing solutions to these types of problems yourself.
168177

178+
{% comment %}
169179
Check out these examples showing the same JSON serialization
170180
implemented three different ways:
171181

172182
- Using the [`JsonCodable` macro][].
173183
- Using the [`json_serializable` code gen package][].
174184
- Manually, [with `dart:convert`][].
185+
{% endcomment %}
175186

176187
[build_runner]: /tools/build_runner
177188
[`JsonCodable` macro]: https://github.com/mit-mit/sandbox/blob/main/explorations/json/dart_jsoncodable/bin/main.dart
@@ -228,7 +239,6 @@ would implement the `ClassDeclarationsMacro` interface:
228239
macro class MyMacro implements ClassDeclarationsMacro {
229240
const MyMacro();
230241
231-
232242
// ...
233243
}
234244
```

0 commit comments

Comments
 (0)