Future.catchError's doc example doesn't emphasize that a valid T must be returned

[srawlins]

The current docs for Future.catchError include this example:

Future.delayed(
  const Duration(seconds: 1),
  () => throw 401,
).then((value) {
  throw 'Unreachable';
}).catchError((err) {
  print('Error: $err'); // Prints 401.
}, test: (error) {
  return error is int && error >= 400;
});

I believe this involves a Future<dynamic>. The catchError onError callback is then allowed to omit a return, as null is a valid dynamic. But it would benefit the user to change this example to use a non-nullable type T, to show that a T must be returned in catchError's onError.

We now catch this statically with a Hint, body_might_complete_normally_catch_error.

[lrhn]

The code is actually just wrong. The type of Future.delayed(..., () => throw 401) is Future<Never>, so the catchError's onError callback must return Never. It doesn't, so there is a runtime error. (It's not compile-time because the onError parameter type is Function).

So, yes, needs fixing.