Some minor improvements to the AsyncSnapshot API (#63347)

packages/flutter/lib/src/widgets/async.dart

@@ -163,6 +163,14 @@ class _StreamBuilderBaseState<T, S> extends State<StreamBuilderBase<T, S>> {
 
 /// The state of connection to an asynchronous computation.
 ///
+/// The usual flow of state is as follows:
+///
+/// 1. [none], maybe with some initial data.
+/// 2. [waiting], indicating that the asynchronous operation has begun,
+///    typically with the data being null.
+/// 3. [active], with data being non-null, and possible changing over time.
+/// 4. [done], with data being non-null.
+///
 /// See also:
 ///
 ///  * [AsyncSnapshot], which augments a connection state with information
@@ -206,6 +214,9 @@ class AsyncSnapshot<T> {
   /// Creates an [AsyncSnapshot] in [ConnectionState.none] with null data and error.
   const AsyncSnapshot.nothing() : this._(ConnectionState.none, null, null);
 
+  /// Creates an [AsyncSnapshot] in [ConnectionState.waiting] with null data and error.
+  const AsyncSnapshot.waiting() : this._(ConnectionState.waiting, null, null);
+
   /// Creates an [AsyncSnapshot] in the specified [state] and with the specified [data].
   const AsyncSnapshot.withData(ConnectionState state, T data) : this._(state, data, null);
 

packages/flutter/test/widgets/async_test.dart

@@ -32,6 +32,14 @@ void main() {
         throwsStateError,
       );
     });
+    test('AsyncSnapshot basic constructors', () {
+      expect(const AsyncSnapshot<int>.nothing().connectionState, ConnectionState.none);
+      expect(const AsyncSnapshot<int>.nothing().data, isNull);
+      expect(const AsyncSnapshot<int>.nothing().error, isNull);
+      expect(const AsyncSnapshot<int>.waiting().connectionState, ConnectionState.waiting);
+      expect(const AsyncSnapshot<int>.waiting().data, isNull);
+      expect(const AsyncSnapshot<int>.waiting().error, isNull);
+    });
   });
   group('Async smoke tests', () {
     testWidgets('FutureBuilder', (WidgetTester tester) async {