[PAGE ISSUE]: 'Fixing type promotion failures'

[jamesderlin]

Page URL

https://dart.dev/tools/non-promotion-reasons.html

Page source

https://github.com/dart-lang/site-www/tree/master/src/tools/non-promotion-reasons.md

Describe the problem

A lot of people are confused that non-local variables aren't automatically promoted by is or null checks. Although https://dart.dev/tools/non-promotion-reasons.html helps explain that the behavior is expected, it doesn't help readers understand the rationale for the behavior, so the inability to promote non-local variables seems arbitrary.

Expected fix

It would be useful to add a note that explains why only local variables can be promoted. Perhaps add links to https://github.com/dart-lang/sdk/issues/21530, https://github.com/dart-lang/sdk/issues/44327, or to https://stackoverflow.com/q/65035574/.

Additional context

No response