[material_ui, cupertino_ui] Recover certain macros that were migrated to avoid @tool leakage #189629

Background

The Flutter framework's API doc has been relying on non-standard directives, such as @tool snippet/sample/dartpad. While migrating directives in the framework to standard dartdoc is generally a long-term goal, some of them are used in @templates and would be leaked into material_ui and cupertino_ui when referenced as macros.

For example, widget CupertinoScrollbar referred to macro flutter.widgets.Scrollbar, which contains a @tool dartpad and a @tool snippet, resulting in the following screenshot:

The following is the full list of such macros:

• flutter.widgets.EditableText.contextMenuBuilder
• flutter.widgets.RawAutocomplete.split
• flutter.widgets.Scrollbar
• flutter.widgets.Scrollbar.controller
• flutter.widgets.Scrollbar.thumbVisibility
• flutter.widgets.editableText.contentInsertionConfiguration
• flutter.widgets.editableText.onChanged
• flutter.widgets.scroll_view.anchor

We can't tell dartdoc to "use this template but convert @tool to @example", and therefore have to rewrite the templates. But some of the macros are pretty lengthy, and duplicating them would sacrifice maintainability.

To unblock the v1.0 release, which were pinned to framework v3.44.0, we migrated the affected macros in material_ui and cupertino_ui in flutter/packages#12271 so that they no longer use the macro, but refer to the base widget instead.

What's needed

We should perform the following changes soon:

• In the framework, move the examples folder to under packages/flutter, and make corresponding changes to relevant tools. This is needed because {@example} requires the example file to be within the package folder.
  • Fixed by Move examples/api to packages/flutter/examples/api and fix CI errors #190481
• In the framework, migrate the affected templates to using standard dartdoc directives.
  • To be fixed by Make check_code_samples.dart‎ support the standard example directives, and migrate some @tool directives #189670

Once the changes above are rolled into the packages, we should revert the changes to the affected macros in material_ui and cupertino_ui.

Non-goal

After all dartdoc features are supported, we should migrate the entire framework to use standard directives. This is out of the scope of this issue.