Add more documentation around keep alive

[ValentinVignal]

Should

• fix Add sample code for AutomaticKeepAliveClientMixin #153860
• fix KeepAlive docs suggest we shouldn't use it, but I believe this might not be a good recommendation #146612
• fix Document relationship between AutomaticKeepAliveClientMixin and addAutomaticKeepAlives #20112

Pre-launch Checklist

• I read the Contributor Guide and followed the process outlined there for submitting PRs.
• I read the Tree Hygiene wiki page, which explains my responsibilities.
• I read and followed the Flutter Style Guide, including Features we expect every widget to implement.
• I signed the CLA.
• I listed at least one issue that this PR fixes in the description above.
• I updated/added relevant documentation (doc comments with ///).
• I added new tests to check the change I am making, or this PR is test-exempt.
• I followed the breaking change policy and added Data Driven Fixes where supported.
• All existing and new tests are passing.

If you need help, consider asking for advice on the #hackers-new channel on Discord.

[victorsanni]

https://github.com/flutter/flutter/blob/master/docs/contributing/Style-guide-for-Flutter-repo.md#use-the-passive-voice-recommend-do-not-require-never-say-things-are-simple

[Piinks]

Thanks for this @ValentinVignal!

[Piinks]

Suggested change

	/// disposed of when they leave the visible area to save resources. This means
	/// disposed of when they leave the visible area to maintain performance. This means

[Piinks]

The fact that some widgets in the framework already have this built-in is really valuable I think. Can we mention it above in the other areas where AutomaticKeepAlive comes up?

[ValentinVignal]

I added it in Add mention of addAutomaticKeepAlives. It felt like having a template for it would be overkill, so I copied and pasted. Tell me what you think about it

[ValentinVignal]

@Piinks @victorsanni Hopefully Use template and passive voice is what you expected

[ValentinVignal]

I'm a bit confused by the failure of "Linux docs_test"

Found unresolved dartdoc directives in /b/s/w/ir/x/w/flutter/dev/docs/doc/flutter/widgets/TreeSliver/addAutomaticKeepAlives.html:
  {@macro flutter.widgets.AutomaticKeepAlive.example}
  {@macro flutter.widgets.KeepAlive.example}
Found unresolved dartdoc directives in /b/s/w/ir/x/w/flutter/dev/docs/doc/flutter/widgets/TwoDimensionalChildListDelegate/addAutomaticKeepAlives.html:
  {@macro flutter.widgets.AutomaticKeepAlive.example}
  {@macro flutter.widgets.KeepAlive.example}
Found unresolved dartdoc directives in /b/s/w/ir/x/w/flutter/dev/docs/doc/flutter/widgets/SliverChildBuilderDelegate/addAutomaticKeepAlives.html:
  {@macro flutter.widgets.AutomaticKeepAlive.example}
  {@macro flutter.widgets.KeepAlive.example}
Found unresolved dartdoc directives in /b/s/w/ir/x/w/flutter/dev/docs/doc/flutter/widgets/TwoDimensionalChildBuilderDelegate/addAutomaticKeepAlives.html:
  {@macro flutter.widgets.AutomaticKeepAlive.example}
  {@macro flutter.widgets.KeepAlive.example}
Found unresolved dartdoc directives in /b/s/w/ir/x/w/flutter/dev/docs/doc/flutter/widgets/SliverChildListDelegate/addAutomaticKeepAlives.html:
  {@macro flutter.widgets.AutomaticKeepAlive.exa

Shouldn't it be solved by adding a

/// @docImport 'automatic_keep_alive.dart';
/// @docImport 'sliver.dart';

at top of the file using the @macro ?

[Piinks]

I think what is happening here is that within the new templates, there are also [references] that would need doc imports.

[ValentinVignal]

I did some digging, it looks like @macro inside @template is not supported dart-lang/dartdoc#2715

@Piinks should I revert what I did for this comment #168311 (comment) and use copy and paste? What do you think is the best to do?

[Piinks]

Oh! So sorry I gave poor advice, I thought we had successfully done this before.

revert what I did for this comment #168311 (comment) and use copy and paste? What do you think is the best to do?

Yes, it sounds like that will be the best course to land this. Sorry again about mistaking the template abilities here.

[ValentinVignal]

No problem at all. It made me run through dartdoc and set up my local to run docs.sh. This is not going to be lost 💪

I reverted the usage of @macro and @template in Revert usage of templates and macros

[victorsanni]

Suggested change

///

[ValentinVignal]

Oops sorry about that, I removed it in Remove empty line in documentation

[victorsanni]

Suggested change

	/// A mixin with convenience methods for clients of [AutomaticKeepAlive]. Used
	/// A mixin with convenience methods for clients of [AutomaticKeepAlive]. It is used

[ValentinVignal]

@Piinks would there be something else you want me to do on this PR ? :)

[Piinks]

Nope, LGTM! Thank you again for your work here!