Would it make sense to phrase it something like "Implementations in subclasses should attach their children after calling the superclass method" (as opposed to "must start with calling the superclass method")? (Maybe with better phrasing, that's not my best work!) The point being to avoid implying that doing unrelated work before calling the superclass is a problem.

Yeah. Perhaps like this?

  /// Subclasses with children should override this method to
  /// [attach] all their children to the same [owner]
  /// after calling the inherited method, as in `super.attach(owner)`.

  /// Subclasses with children should override this method to
  /// [detach] all their children after calling the inherited
  /// method, as in `super.detach()`.

That is:

• Subclasses with children should override this method. (Other subclasses may or may not need to.)
• Specifically, they should attach/detach all their children.
• They should do that after the super call (but the ordering vs. any other work is unspecified).

This version (unlike what's in main) doesn't mention that implementations even in subclasses without children should call the superclass method. But @mustCallSuper means the linter will cover that, so that seems OK.

SGTM.

Cool. Pushed a revision with that text.

auto label is removed for flutter/flutter, pr: 130688, due to - The status or check suite Google testing has failed. Please fix the issues identified (or deflake) before re-applying this label.