Add links to explain behavior on 'Fixing type promotion failures' page

[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 dart-lang/sdk#21530, dart-lang/sdk#44327, or to https://stackoverflow.com/q/65035574/.

Additional context

No response

[atsansone]

@MaryaBelanger : FYI. Not sure if this folds into your existing Type Promotion planning.

[parlough]

c7e458c almost completely overhauled this page with expanded explanations of the different situations where promotion couldn't occur and why, samples, and solutions. (Thanks Marya!!)

As a result, I'm going to close this, but if you see any missing cases or ones which still need further elaboration, please open a new issue. Thanks so much for raising this!

I will note that even the updated docs don't go too deep into the type theory or implementation reasons if that's what you're looking for, but this page doesn't seem a good place for that explanation anyway. There are plans to introduce completely new type system documentation eventually which should provide some more useful resources in this area though.