linter: Document and test more specifically what the rule does

In preparation for the `@awaitNotRequired` annotation, I looked into
the implementation of this rule, and changed the documentation to be
more specific about the very specific situations in which lints are
reported (there are only three). This should alleviate issues like
#60006.

I also added some test cases that will be useful in exploring what the
new annotation will be able to suppress.

Change-Id: Iea3a90b6c79df4b8eee7c33063780b3cf0298109
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/415780
Commit-Queue: Samuel Rawlins <[email protected]>
Reviewed-by: Phil Quitslund <[email protected]>

Author: srawlins

pkg/linter/lib/src/rules/unawaited_futures.dart

@@ -54,18 +54,20 @@ class _Visitor extends SimpleAstVisitor<void> {
     if (type == null) {
       return;
     }
-    if (type.implementsInterface('Future', 'dart.async')) {
-      // Ignore a couple of special known cases.
-      if (_isFutureDelayedInstanceCreationWithComputation(expr) ||
-          _isMapPutIfAbsentInvocation(expr)) {
-        return;
-      }
-
-      if (_isEnclosedInAsyncFunctionBody(node)) {
-        // Future expression statement that isn't awaited in an async function:
-        // while this is legal, it's a very frequent sign of an error.
-        rule.reportLint(node);
-      }
+    if (!type.implementsInterface('Future', 'dart.async')) {
+      return;
+    }
+
+    // Ignore a couple of special known cases.
+    if (_isFutureDelayedInstanceCreationWithComputation(expr) ||
+        _isMapPutIfAbsentInvocation(expr)) {
+      return;
+    }
+
+    if (_isEnclosedInAsyncFunctionBody(node)) {
+      // Future expression statement that isn't awaited in an async function:
+      // while this is legal, it's a very frequent sign of an error.
+      rule.reportLint(node);
     }
   }
 
@@ -97,6 +99,7 @@ class _Visitor extends SimpleAstVisitor<void> {
       _isMapClass(expr.methodName.element?.enclosingElement2);
 
   void _visit(Expression expr) {
+    // TODO(srawlins): Check whether `expr`'s static type _implements_ `Future`.
     if ((expr.staticType?.isDartAsyncFuture ?? false) &&
         _isEnclosedInAsyncFunctionBody(expr) &&
         expr is! AssignmentExpression) {

pkg/linter/messages.yaml

@@ -11438,10 +11438,18 @@ LintCode:
     documentation: |-
       #### Description
 
-      The analyzer produces this diagnostic when an instance of `Future` is
-      returned from an invocation within an `async` (or `async*`) method or
-      function and the future is neither awaited nor passed to the `unawaited`
-      function.
+      The analyzer produces this diagnostic on an expression with a `Future`
+      type, only in a few specific cases:
+
+      * when the expression is itself a statement (like `f();`),
+      * when the expression is part of a cascade (like `C()..f()`),
+      * when the expression is a String interpolation (like `'${f()}'`).
+
+      The analyzer only produces this diagnostic on expressions inside an
+      `async` or `async*` function.
+
+      The two common corrections are to 'await' the expression, or to wrap the
+      expression in a call to `unawaited()`.
 
       #### Example
 

pkg/linter/test/rules/unawaited_futures_test.dart

@@ -17,6 +17,30 @@ class UnawaitedFuturesTest extends LintRuleTest {
   @override
   String get lintRule => LintNames.unawaited_futures;
 
+  test_binaryExpression_unawaited() async {
+    await assertDiagnostics(
+      r'''
+void f(C a, C b) async {
+  a + b;
+}
+class C {
+  Future<int> operator +(C other) async => 7;
+}
+''',
+      [lint(27, 6)],
+    );
+  }
+
+  test_boundToFuture_unawaited() async {
+    // This behavior was not necessarily designed, but this test documents the
+    // current behavior.
+    await assertNoDiagnostics(r'''
+void f<T extends Future<void>>(T p) async {
+  p;
+}
+''');
+  }
+
   test_classImplementsFuture() async {
     // https://github.com/dart-lang/linter/issues/2211
     await assertDiagnostics(
@@ -72,6 +96,18 @@ Future<int> g() => Future.value(0);
     );
   }
 
+  test_functionCall_nullableFuture_unawaited() async {
+    await assertDiagnostics(
+      r'''
+void f() async {
+  g();
+}
+Future<int>? g() => Future.value(0);
+''',
+      [lint(19, 4)],
+    );
+  }
+
   test_functionCall_returnedWithFutureType() async {
     await assertNoDiagnostics(r'''
 void f() async {
@@ -143,6 +179,45 @@ class C {
 ''');
   }
 
+  test_instanceProperty_unawaited() async {
+    await assertDiagnostics(
+      r'''
+void f(C c) async {
+  c.p;
+}
+abstract class C {
+  Future<int> get p;
+}
+''',
+      [lint(22, 4)],
+    );
+  }
+
+  test_parameter_unawaited() async {
+    await assertDiagnostics(
+      r'''
+void f(Future<int> p) async {
+  p;
+}
+''',
+      [lint(32, 2)],
+    );
+  }
+
+  test_unaryExpression_unawaited() async {
+    await assertDiagnostics(
+      r'''
+void f(C a) async {
+  -a;
+}
+class C {
+  Future<int> operator -() async => 7;
+}
+''',
+      [lint(22, 3)],
+    );
+  }
+
   test_undefinedIdentifier() async {
     await assertDiagnostics(
       r'''