[Future] Macros feature docs plan

[MaryaBelanger]

Breaking out the "Future" section from #5692

---

Once the serialization macro is stable, add it as the recommended json serialization option:

• Start with the JSON page
  • Page needs expanding in general, then macro content will fit more naturally there:
    • Expand 'Using JSON' page into a proper guide for JSON #4286
    • Add extension types to JSON page #5605
    • Add link to patterns codelab to JSON page
  • The page should take an explicit stance early on that the macro is the best option for json serialization.
  • Describe usage of the macro in a section on the page.
    • This content will be moved from the language/macros page to the JSON page
• The JSON and serialization page on flutter.dev.
  • The page should take an explicit stance early on that the macro is the best option for json serialization.
  • Since part of #4286 is consolidating the Dart-specific content from the flutter page onto the dart page, including information about the macro will likely just mean pointing to the main content on dart.dev’s JSON page.

---

Once writing a macro is available to users, document how to write macros:

• Change the experimental language/macros page to be the main landing page for the language feature, focus on writing macros
• Document the different interfaces macros can use, what they can be applied to and what types of things they can do.
  • E.g. ... implements ClassDeclarationsMacro = can be applied to a class, and adds new declarations to the class. Document all options and characteristics.
• Building up code as a string basically with builder.declareInType, etc
• Macros that use other macros, encapsulating logic (like ToJson and FromJson in JsonSerializable)
• How to write a configuration annotation (e.g. json_key.dart) and have your macro use it (FieldDeclaration/FieldConfig?)
• How to write custom diagnostics

---

Document Augmentation as a separate feature, referenced by the macros content.

• No notes yet, will possibly expand into separate issue.

[parlough]

Closing this for now in relation to the macros update. Thanks for all of the consideration and work here though!