linter: Add documentation to the 'unnecessary_unawaited' lint rule

Change-Id: I2e46a3bdbbe40ae3e0e383eb75357ea38ea95596
Reviewed-on: https://dart-review.googlesource.com/c/sdk/+/428581
Reviewed-by: Brian Wilkerson <[email protected]>
Commit-Queue: Samuel Rawlins <[email protected]>

Author: srawlins

pkg/linter/messages.yaml

@@ -13593,11 +13593,50 @@ LintCode:
       stable: "3.9"
     categories: [brevity, unintentional, unusedCode]
     hasPublishedDocs: false
+    documentation: |-
+      #### Description
+
+      The analyzer produces this diagnostic when `unawaited` is used to mark a
+      call to a function, method, or operator, or a reference to a field,
+      getter, or top-level variable as safely not being awaited, but the called
+      member is also annotated with `@awaitNotRequired`. This annotation itself
+      signals that wrapping with `unawaited` is unnecessary at any call site.
+
+      #### Example
+
+      The following code produces this diagnostic because `unawaited` is invoked
+      on a call to a function that's annotated with `@awaitNotRequired`:
+
+      ```dart
+      import 'dart:async';
+      import 'package:meta/meta.dart';
+
+      @awaitNotRequired
+      Future<bool> log(String message) async => true;
+
+      void f() {
+        [!unawaited!](log('Message.'));
+      }
+      ```
+
+      #### Common fixes
+
+      Remove the invocation of `unawaited`:
+
+      ```dart
+      import 'package:meta/meta.dart';
+
+      @awaitNotRequired
+      Future<bool> log(String message) async => true;
+
+      void f() {
+        log('Message.');
+      }
+      ```
     deprecatedDetails: |-
       A call to a function, method, or operator, or a reference to a field,
       getter, or top-level variable which is annotated with `@awaitNotRequired`
-      does not necessarily need to be awaited, nor does it need to be wrapped in
-      a call to `unawaited()`.
+      does not need to be wrapped in a call to `unawaited()`.
 
       **BAD:**
       ```dart