Add long error explanation for E0728

Author: JohnTitor

src/librustc/error_codes.rs

@@ -2045,8 +2045,8 @@ so that a generator can then be constructed:
 async fn bar<T>() -> () {}
 
 async fn foo() {
-  bar::<String>().await;
-  //   ^^^^^^^^ specify type explicitly
+    bar::<String>().await;
+    //   ^^^^^^^^ specify type explicitly
 }
 ```
 "##,
@@ -2126,6 +2126,74 @@ static X: u32 = 42;
 ```
 "##,
 
+E0728: r##"
+`await` has been used outside `async` function or block.
+
+Erroneous code examples:
+
+```edition2018,compile_fail,E0728
+# use std::pin::Pin;
+# use std::future::Future;
+# use std::task::{Context, Poll};
+
+# struct WakeOnceThenComplete(bool);
+
+# fn wake_and_yield_once() -> WakeOnceThenComplete {
+#     WakeOnceThenComplete(false)
+# }
+
+# impl Future for WakeOnceThenComplete {
+#     type Output = ();
+#     fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<()> {
+#         if self.0 {
+#             Poll::Ready(())
+#         } else {
+#             cx.waker().wake_by_ref();
+#             self.0 = true;
+#             Poll::Pending
+#         }
+#     }
+# }
+
+fn foo() {
+    wake_and_yield_once().await // `await` is used outside `async` context
+}
+```
+
+`await` is used to suspend the current computation until the given
+future is ready to produce a value. So it is legal only within
+an async context, like an `async fn` or an `async` block.
+
+```edition2018
+# use std::pin::Pin;
+# use std::future::Future;
+# use std::task::{Context, Poll};
+
+# struct WakeOnceThenComplete(bool);
+
+# fn wake_and_yield_once() -> WakeOnceThenComplete {
+#     WakeOnceThenComplete(false)
+# }
+
+# impl Future for WakeOnceThenComplete {
+#     type Output = ();
+#     fn poll(mut self: Pin<&mut Self>, cx: &mut Context<'_>) -> Poll<()> {
+#         if self.0 {
+#             Poll::Ready(())
+#         } else {
+#             cx.waker().wake_by_ref();
+#             self.0 = true;
+#             Poll::Pending
+#         }
+#     }
+# }
+
+async fn foo() {
+    wake_and_yield_once().await // `await` is used within `async` context
+}
+```
+"##,
+
 E0734: r##"
 A stability attribute has been used outside of the standard library.
 
@@ -2218,6 +2286,5 @@ See [RFC 2091] for details on this and other limitations.
 //  E0702, // replaced with a generic attribute input check
     E0726, // non-explicit (not `'_`) elided lifetime in unsupported position
     E0727, // `async` generators are not yet supported
-    E0728, // `await` must be in an `async` function or block
     E0739, // invalid track_caller application/syntax
 }

src/test/ui/async-await/await-keyword/incorrect-syntax-suggestions.stderr

@@ -244,4 +244,5 @@ LL |     let _ = await bar()?;
 
 error: aborting due to 35 previous errors
 
-For more information about this error, try `rustc --explain E0277`.
+Some errors have detailed explanations: E0277, E0728.
+For more information about an error, try `rustc --explain E0277`.

src/test/ui/async-await/issues/issue-51719.stderr

@@ -8,3 +8,4 @@ LL |     let _gen = || foo().await;
 
 error: aborting due to previous error
 
+For more information about this error, try `rustc --explain E0728`.

src/test/ui/async-await/issues/issue-51751.stderr

@@ -9,3 +9,4 @@ LL |     let finished = result.await;
 
 error: aborting due to previous error
 
+For more information about this error, try `rustc --explain E0728`.

src/test/ui/async-await/issues/issue-62009-1.stderr

@@ -40,4 +40,5 @@ LL |     F: Future
 
 error: aborting due to 4 previous errors
 
-For more information about this error, try `rustc --explain E0277`.
+Some errors have detailed explanations: E0277, E0728.
+For more information about an error, try `rustc --explain E0277`.

src/test/ui/async-await/issues/issue-62009-2.stderr

@@ -8,3 +8,4 @@ LL |     (async || 2333)().await;
 
 error: aborting due to previous error
 
+For more information about this error, try `rustc --explain E0728`.

src/test/ui/async-await/issues/non-async-enclosing-span.stderr

@@ -9,3 +9,4 @@ LL |     let y = do_the_thing().await;
 
 error: aborting due to previous error
 
+For more information about this error, try `rustc --explain E0728`.