Skip to content

Add more documentation around keep alive #168311

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 8 commits into
base: master
Choose a base branch
from
Open

Add more documentation around keep alive #168311

wants to merge 8 commits into from

Conversation

ValentinVignal
Copy link
Contributor

@ValentinVignal ValentinVignal commented May 5, 2025 •
edited
Loading

Should

Pre-launch Checklist

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

@github-actions github-actions bot added framework flutter/packages/flutter repository. See also f: labels. f: scrolling Viewports, list views, slivers, etc. labels May 5, 2025
ValentinVignal
ValentinVignal commented May 5, 2025
View reviewed changes
ValentinVignal
ValentinVignal commented May 5, 2025
View reviewed changes
victorsanni
victorsanni reviewed May 13, 2025
View reviewed changes
packages/flutter/lib/src/widgets/sliver.dart Outdated
Comment on lines 1461 to 1462
/// To manage keep-alive behavior, you can use [KeepAlive] directly or rely on
/// notifications. For convenience, you can also mix
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Piinks reviewed May 13, 2025
View reviewed changes
Copy link
Contributor

@Piinks Piinks left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for this @ValentinVignal!

packages/flutter/lib/src/widgets/scroll_delegate.dart Outdated
/// the state of individual items in a scrollable list.
///
/// Normally, widgets in a lazily built list like [ListView.builder] are
/// disposed of when they leave the visible area to save resources. This means
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

packages/flutter/lib/src/widgets/sliver.dart
/// [TwoDimensionalViewport], to manage the lifecycle of widgets that need to
/// remain alive even when scrolled out of view.
///
/// The [SliverChildBuilderDelegate] and [SliverChildListDelegate] delegates,
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Contributor Author

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

@ValentinVignal
Copy link
Contributor Author

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
Copy link
Contributor

Piinks commented May 20, 2025

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

@ValentinVignal
Copy link
Contributor Author

ValentinVignal commented May 21, 2025 •
edited
Loading

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
Copy link
Contributor

Piinks commented May 21, 2025

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
Copy link
Contributor Author

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
victorsanni reviewed May 23, 2025
View reviewed changes
packages/flutter/lib/src/widgets/scroll_delegate.dart Outdated
@@ -413,6 +413,61 @@ class SliverChildBuilderDelegate extends SliverChildDelegate {
/// none of the children will ever try to keep themselves alive.
///
/// Defaults to true.
///
///
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
///

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

@ValentinVignal @victorsanni
Remove empty line in documentation
0e751b1 
Co-authored-by: Victor Sanni <victorsanniay@gmail.com>
victorsanni
victorsanni approved these changes May 23, 2025
View reviewed changes
packages/flutter/lib/src/widgets/automatic_keep_alive.dart Outdated
@@ -355,7 +372,18 @@ class KeepAliveHandle extends ChangeNotifier {
}

/// A mixin with convenience methods for clients of [AutomaticKeepAlive]. Used
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 @victorsanni
Better documentation
2bb9082 
Co-authored-by: Victor Sanni <victorsanniay@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@victorsanni victorsanni victorsanni approved these changes

@bleroux bleroux Awaiting requested review from bleroux

@Piinks Piinks Awaiting requested review from Piinks

Assignees
No one assigned
Labels
f: scrolling Viewports, list views, slivers, etc. framework flutter/packages/flutter repository. See also f: labels.
Projects
None yet
Milestone
No milestone
3 participants
@ValentinVignal @Piinks @victorsanni
pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy