Explain why build methods must not have side effects - #188939

This statement, while correct, can be a bit of a footgun. A common mistake is to set the controller's text from within its own listener, which can easily lead to an infinite loop of notifications.

Since this whole documentation block is about preventing unexpected behavior, it would be beneficial to add a word of caution here. I'd suggest separating this point into its own paragraph and expanding on the potential pitfalls and how to avoid them.

  /// build that sets the text again.
  ///
  /// This property can be set from a listener added to this [TextEditingController].
  /// When doing so, care should be taken to avoid infinite loops. A listener that
  /// sets text will be called again, so a common pattern is to first remove the
  /// listener, then set the text, and then re-add the listener.

Good call — added a paragraph in 1ffa759 warning about the listener-loop footgun and suggesting the remove-set-re-add pattern to avoid it.

I think the explanation is too lengthy. Also using this method in production code is already discouraged:

/// This setter is typically only used in tests, as it resets the cursor

Trimmed it down in 613979d. The setter is already documented as "typically only used in tests", so I've cut the explanation to the part that isn't obvious from that — that setting it notifies listeners, and so it must not happen during build/layout/paint. The infinite-loop paragraph is gone; it was over-explaining a setter that production code shouldn't be reaching for anyway.

This sounds like this is describing idempotency instead of being "side-effect-free" (it's a bit pedantic but I think idempotency is the more accurate right term here?)

You're right, and it's not pedantic — idempotency is the accurate constraint. "No side effects" describes the symptom, but the actual requirement is that the framework may call build arbitrarily often, so calling it repeatedly has to have the same effect as calling it once. Reworded to lead with that in 613979d, which also let me drop the enumeration of side effects and shorten the whole block.

The additions here don't add too much value, I recommend swapping them out with a reference to the build docs.

Good call — done in b46d414. I've reverted the prose here to exactly what was on master and replaced my additions with a pointer instead:

/// See also:
///
///  * [StatelessWidget.build], which explains why a build method must not
///    have side effects such as setting this value.

That keeps the explanation in one place (the {@template flutter.widgets.StatelessWidget.build.noSideEffects} block this PR adds in framework.dart, which State.build already pulls in via {@macro}) rather than restating a shortened version of it here. The editable_text.dart side of the diff is now just those five lines.

I also merged master in — the branch had drifted 186 commits and was carrying a stale .ci.yaml, which was enough to fail presubmit on a sibling PR of mine.