Plan for macros documentation work in the Dart 3.4 release.

Summary

A single json serialization macro will be in main (probably behind a flag) by the 3.4 release. The feature will be advertised alongside this release, so we'll create an "experiment" page for users to learn more from when they hear about the feature.

Users will not be able to write their own macros in the 3.4 stable release.

Goals

• Introduce users to macros before the full implementation is complete.
• Teach users how to use the new json serialization macro.
• Showcase the cool features of macros and get users excited for the upcoming feature.
• Be VERY clear this is not available yet
  • Main feature completely unavailable, loose/hopeful timeline
  • Example macro behind flag, how to try it out

Doc plan/eval

• Create a page at dart.dev/language/macros
• Hide from the side nav for now
• Redirect temporary link: Create content and change redirect for dart.dev/macros #5685
• Clear note at the top about availability / timeline (or lack thereof)
  • (from comment): direction on where to leave feedback (different repos, language, analyzer, specific issues? etc), what levels of feedback are welcome, etc
• Introduce macros at a high-level, how they work (feature as planned), why they're cool
  • General flow: custom macro, configurations, diagnostics, using a macro, generated augmentation, etc.
  • User experience improvements over other codegen:
    • integrated into Dart, don't have to run anything separate
    • no referencing weird generated symbols, things get added directly
    • significantly faster than other codegen
    • massively improved test experience
• Introduce serialization macro, how to use it / development experience of using it:
  • This section will eventually move to the JSON serialization page
  • Benefits over other serialization options
  • Actual steps with examples:
    • Append annotation, creates ToJson method and FromJson constructor
    • Use any configurations
    • Show the augmentation file/updating (e.g. change field name, comment out annotation) in real time in the IDE
    • Emitting custom diagnostics
  • (maybe) Basic "migration" from json serializable package?
    • remove part, change annotation name, dart run yourProgram instead of running buildrunner, etc...

Future

#5722

Resources

• Serialization macro code: https://github.com/dart-lang/sdk/tree/main/tests/language/macros/json:
  • The macro itself json_serializable.dart
  • Tests (closest to usage example) json_serializable_test.dart
  • Annotation used alongside macro json_key.dart
• Static metaprogramming language issue
• Feature spec
• Previous serialization solutions:
  • (json_serializable package)
    • Example of using previous solution
    • Example of generated code from existing serialization code generator example.g.dart