From 8a19145f3e8a8cfa3ec299ead953f56924bb89ed Mon Sep 17 00:00:00 2001 From: chunhtai <47866232+chunhtai@users.noreply.github.com> Date: Thu, 4 Jun 2020 10:18:02 -0700 Subject: [PATCH] =?UTF-8?q?update=20build=20doc=20string=20to=20advocate?= =?UTF-8?q?=20avoiding=20doing=20tasks=20other=20than=20b=E2=80=A6=20(#582?= =?UTF-8?q?13)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- packages/flutter/lib/src/widgets/async.dart | 6 ++++++ packages/flutter/lib/src/widgets/framework.dart | 14 ++++++++++---- 2 files changed, 16 insertions(+), 4 deletions(-) diff --git a/packages/flutter/lib/src/widgets/async.dart b/packages/flutter/lib/src/widgets/async.dart index 5880bbb97e..2692ad8b5a 100644 --- a/packages/flutter/lib/src/widgets/async.dart +++ b/packages/flutter/lib/src/widgets/async.dart @@ -471,6 +471,9 @@ class StreamBuilder extends StreamBuilderBase> { super(key: key, stream: stream); /// The build strategy currently used by this builder. + /// + /// This builder must only return a widget and should not have any side + /// effects as it may be called multiple times. final AsyncWidgetBuilder builder; /// The data that will be used to create the initial snapshot. @@ -686,6 +689,9 @@ class FutureBuilder extends StatefulWidget { /// the value to which the future completed. If it completed with an error, /// [AsyncSnapshot.hasError] will be true and [AsyncSnapshot.error] will be /// set to the error object. + /// + /// This builder must only return a widget and should not have any side + /// effects as it may be called multiple times. final AsyncWidgetBuilder builder; /// The data that will be used to create the snapshots provided until a diff --git a/packages/flutter/lib/src/widgets/framework.dart b/packages/flutter/lib/src/widgets/framework.dart index 2c895b717d..ff014ad9e4 100644 --- a/packages/flutter/lib/src/widgets/framework.dart +++ b/packages/flutter/lib/src/widgets/framework.dart @@ -662,9 +662,11 @@ abstract class StatelessWidget extends Widget { /// Describes the part of the user interface represented by this widget. /// - /// The framework calls this method when this widget is inserted into the - /// tree in a given [BuildContext] and when the dependencies of this widget - /// change (e.g., an [InheritedWidget] referenced by this widget changes). + /// The framework calls this method when this widget is inserted into the tree + /// in a given [BuildContext] and when the dependencies of this widget change + /// (e.g., an [InheritedWidget] referenced by this widget changes). This + /// method can potentially be called in every frames should not have any side + /// effects beyond building a widget. /// /// The framework replaces the subtree below this widget with the widget /// returned by this method, either by updating the existing subtree or by @@ -1315,7 +1317,8 @@ abstract class State with Diagnosticable { /// Describes the part of the user interface represented by this widget. /// - /// The framework calls this method in a number of different situations: + /// The framework calls this method in a number of different situations. For + /// example: /// /// * After calling [initState]. /// * After calling [didUpdateWidget]. @@ -1325,6 +1328,9 @@ abstract class State with Diagnosticable { /// * After calling [deactivate] and then reinserting the [State] object into /// the tree at another location. /// + /// This method can potentially be called in every frames and should not have + /// any side effects beyond building a widget. + /// /// The framework replaces the subtree below this widget with the widget /// returned by this method, either by updating the existing subtree or by /// removing the subtree and inflating a new subtree, depending on whether the