docs(crashlytics): Improve Crashlytics documentation around catching sync/async exceptions.

[K9i-0]

Description

This PR updates the documentation to clarify error handling and exception reporting with FirebaseCrashlytics in Flutter applications. The changes aim to provide clearer instructions for developers integrating FirebaseCrashlytics.

• The original text written for using runZonedGuarded was unnatural.

  • 47e7b80

• The documentation's phrasing has been updated based on the example code.

  • 272a9d2

Related Issues

None. This PR is not related to any existing issues from the issue database.

Checklist

Before you create this PR confirm that it meets all requirements listed below by checking the relevant checkboxes ([x]).
This will ensure a smooth and quick review process. Updating the pubspec.yaml and changelogs is not required.

• I read the Contributor Guide and followed the process outlined there for submitting PRs.
• My PR includes unit or integration tests for all changed/updated/fixed behaviors (See Contributor Guide).
• All existing and new tests are passing.
• I updated/added relevant documentation (doc comments with ///).
• The analyzer (melos run analyze) does not report any problems on my PR.
• I read and followed the Flutter Style Guide.
• I signed the CLA.
• I am willing to follow-up on review comments in a timely manner.

Breaking Change

Does your PR require plugin users to manually update their apps to accommodate your change?

• Yes, this is a breaking change.
• No, this is not a breaking change.

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[russellwheatley]

This should look something like this:

const fatalError = true;
  FlutterError.onError = (errorDetails) {
    if (fatalError) {
      // If you wish to record a "fatal" exception
      FirebaseCrashlytics.instance.recordFlutterFatalError(errorDetails);
    } else {
      // If you wish to record a "non-fatal" exception
      FirebaseCrashlytics.instance.recordFlutterError(errorDetails);
    }
  };

Also - please update this part to look like this:

 const fatalError = true;
  PlatformDispatcher.instance.onError = (error, stack) {
    if (fatalError) {
      // If you wish to record a "fatal" exception
      FirebaseCrashlytics.instance.recordError(error, stack, fatal: true);
    } else {
      // If you wish to record a "non-fatal" exception
      FirebaseCrashlytics.instance.recordError(error, stack);
    }
    return true;
  };

It would also be cool if you updated the example app here so it looked like this:

const fatalError = true;
  // Non-async exceptions
  FlutterError.onError = (errorDetails) {
    if (fatalError) {
      // If you wish to record a "fatal" exception
      FirebaseCrashlytics.instance.recordFlutterFatalError(errorDetails);
    } else {
      // If you wish to record a "non-fatal" exception
      FirebaseCrashlytics.instance.recordFlutterError(errorDetails);
    }
  };
  // Async exceptions
  PlatformDispatcher.instance.onError = (error, stack) {
    if (fatalError) {
      // If you wish to record a "fatal" exception
      FirebaseCrashlytics.instance.recordError(error, stack, fatal: true);
    } else {
      // If you wish to record a "non-fatal" exception
      FirebaseCrashlytics.instance.recordError(error, stack);
    }
    return true;
  };

[K9i-0]

I have updated it.
4c74317

[russellwheatley]

@kevinthecheung - we've made some changes to Crashlytics documentation if you could give it a review, that would be great. Thanks.

[rachelsaunders]

Throughout --

1. pls change "wish" to "want"
2. pls remove the word "please" (we don't use "please" in our tech docs)

[mrober]

Would it be more succinct to have fatal: fatalError on this line instead of the if statement?

[russellwheatley]

@K9i-0 - do you mind changing the above mentioned by @rachelsaunders & @mrober, please? We can get this PR merged once done. Thanks.

[russellwheatley]

Closing in favour of: #11275