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.

[jamesderlin]

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.

I agree that this page isn't the right place to provide those explanations, which is why my suggestion was to provide links to other sources for those details. I do still think that this page is the right place to provide such links.

[parlough]

That makes sense, thanks for clarifying! I took a closer look at some of the links you shared and it seems the new additions to the page do a decent job of covering the "why" like discussed in those.

For example, when explaining why getters can't be promoted:

The compiler has no way to guarantee that a getter returns the same result every time. Because their stability can’t be confirmed, getters are not safe to promote.

And another when discussing external fields:

External fields don’t promote because they are essentially external getters; their implementation is code from outside of Dart, so there’s no guarantee for the compiler that an external field will return the same value each time it’s called.

If you get a chance, could you take a look and see if any particular explanation is missing or not sufficient? If so, we definitely should consider expanding the explanation.