[2.19] runZoned docs

[MaryaBelanger]

Parent:

dart-lang/sdk#49679

Evaluation:

• Update needed:
  • https://dart.dev/articles/archive/zones : runZoned with onError used
  • Page is archived, what's the policy there? Update and take out of archive?
    • Will take care of in a separate issue: Update and improve or replace the zones page #4348
• No entry in change log yet, add
  • The only changes here are to the API docs, onError was already deprecated in a past release. I don't think cathcing up on API docs changes warrant an item in the change log
  • But still warrants mention in 'What's new' page

Reference:

• API docs already updated, use new syntax: dart-lang/sdk@59cd692
• This issue better describes the change from runZoned with onError to runZoned and runZonedGuarded
• Some examples of runZonedGuarded in use:
  • errorZone API
  • (error, stackTrace) example
  • (dynamic error, StackTrace stackTrace) example
  • other error handler output

[parlough]

The zones article is heavily outdated, in both the code examples and some of the explanations with much of it predating Dart 2. It's definitely not idiomatic anymore. The writing and formatting of the website has heavily changed since then too.

Users want to learn more about zones though, so I would like to see the article updated. Starting with getting the code examples functional currently and then adjusting for the 2.19 changes when that comes around would be a good start.

[MaryaBelanger]

@parlough So, this doesn't need to be rolled out with the 2.19 release, necessarily? It sounds like an improvement issue vs. a fix. Just want to clarify

[parlough]

The removal of onError from runZoned does require changes/fixes to the article with the 2.19 release.

I'm just highlighting other changes are needed to get the article compatible with even Dart 2.18 (hence the current archived state), so perhaps that's a higher priority, first step that should be completed first.

[MaryaBelanger]

@parlough could you help me figure out where to view the changes made in this commit in api.dart.dev? I've found that lines 1696-1726 seem to correspond to here... but I can't find some of the other new stuff/changes. Eg, where do the examples between lines 624 and 668 show up in the API docs?

How can I learn to interpret API doc changes better going forward?

I'd like to see the new examples of runZonedGuarded rendered in the API docs (it's hard to assess what the samples look like in the diff :/)

Appreciate your time! 🙏

[parlough]

It seems some of those changes might be on the properties of the Zone class itself. For example, lines 624 through 688 are on the errorZone property of the class.

It's sometimes bit hard to see, especially on Gerrit, but to find where doc changes are, I scroll down to find the class, property, or method they are attached to, then I search for that. For example when searching for errorZone, the first result is that Zone property. If there are multiple results, I scroll up to find the class the method or property is part of.

[MaryaBelanger]

Small related fix in API docs: https://dart-review.googlesource.com/c/sdk/+/272488

[MaryaBelanger]

Fixing PRs merged into v2.19