log [nfc]: Revise reportErrorToUserBriefly doc; tweak related comments

Author: gnprice

lib/log.dart

@@ -33,10 +33,12 @@ bool debugLog(String message) {
 
 typedef ReportErrorCallback = void Function(String? message, {String? details});
 
-/// Display an error message in a [SnackBar].
+/// Show the user an error message, without requiring them to interact with it.
 ///
-/// This shows a [SnackBar] containing the message if [ZulipApp] is ready,
-/// otherwise logs it to the console.
+/// Typically this shows a [SnackBar] containing the message.
+/// If called before the app's widget tree is ready (see [ZulipApp.ready]),
+/// then we give up on showing the message to the user,
+/// and just log the message to the console.
 ///
 /// If `message` is null, this will clear the existing [SnackBar]s if there
 /// are any.  Useful for promptly dismissing errors.

lib/widgets/app.dart

@@ -98,13 +98,14 @@ class ZulipApp extends StatefulWidget {
 
   static int _snackBarCount = 0;
 
+  /// The callback we normally use as [reportErrorToUserBriefly].
   static void _reportErrorToUserBriefly(String? message, {String? details}) {
     assert(_ready.value);
 
     if (message == null) {
       if (_snackBarCount == 0) return;
       assert(_snackBarCount > 0);
-      // The snack bar API only exposes ways to hide ether the current snack
+      // The [SnackBar] API only exposes ways to hide ether the current snack
       // bar or all of them.
       //
       // To reduce the possibility of hiding snack bars not created by this