Clarify documentation about when Flutter stops rebuilding

[derolf]

In the best-practies it reads:

The traversal to rebuild all descendents stops when the same instance of the child widget as the previous frame is re-encountered.

People confuse "same" with "equal" vs "identical". So, the question raises whether Flutter is using the operator== or the identical function to determine when to stop rebuilding. Here is the code from framework.dart:

  if (child.widget == newWidget) {
    if (child.slot != newSlot)
      updateSlotForChild(child, newSlot);
    return child;
  }

Obviously, "same instance" in the docs is highly misleading and it should rather read "equal instances". Hence, two non-identical widgets with the same runtime-type and key that are equal with respect to == will stop rebuilding. That's an important aspect for performance optimisations.

For sure, the operator== defaults to identical in Dart, hence overriding operator== for a Widget is required to let the optimisation kick in.

I think it would make sense to clarify that in the docs. (Replace "same" with "equal" and elaborate on the fact.)

Link to Stackoverflow:

• https://stackoverflow.com/questions/57530086/does-overriding-operator-help-to-avoid-rebuilding

[whesse]

Another place in the documentation where this is unclear is in the documentation of the StatelessWidget class.

It says
The build method of a stateless widget is typically only called in three situations: the first time the widget is inserted in the tree, when the widget's parent changes its configuration, and when an InheritedWidget it depends on changes.

It is unclear what "configuration" means here, it seems to be the arguments to the widget's constructor.

It is unclear whether the "first time the widget is inserted in the tree" means the first time a widget of this type is inserted at this location in the tree, or the first time this widget instance is inserted in the tree. Neither seems to be correct.

When the parent rebuilds, and an identical, an equal, or a constant (identical) widget instance appears here, the build method won't be (necessarily) called. If the parent build method introduces a new instance of the same widget, even with the same constructor arguments, its build method will be called unless operator== says it is equal to the previous instance.

[github-actions]

This thread has been automatically locked since there has not been any recent activity after it was closed. If you are still experiencing a similar issue, please open a new bug, including the output of flutter doctor -v and a minimal reproduction of the issue.