Fill in prose to describe the async_fn_in_trait lint

We're stabilizing `async fn` in trait (AFIT), but we have some
reservations about how people might use this in the definitions of
publicly-visible traits, so we're going to lint about that.

This is a bit of an odd lint for `rustc`.  We normally don't lint just
to have people confirm that they understand how Rust works.  But in
this one exceptional case, this seems like the right thing to do as
compared to the other plausible alternatives.

In this commit, we describe the nature of this odd lint.

Author: traviscross

Diff for: compiler/rustc_lint/messages.ftl

@@ -5,9 +5,9 @@ lint_array_into_iter =
     .use_explicit_into_iter_suggestion =
         or use `IntoIterator::into_iter(..)` instead of `.into_iter()` to explicitly iterate by value
 
-lint_async_fn_in_trait = usage of `async fn` in trait is discouraged because they do not automatically have auto trait bounds
-    .note = you can suppress this lint if you plan to use the trait locally, for concrete types, or do not care about auto traits like `Send` on the future
-    .suggestion = you can alternatively desugar the `async fn` and any add additional traits such as `Send` to the signature
+lint_async_fn_in_trait = use of `async fn` in public traits is discouraged as auto trait bounds cannot be specified
+    .note = you can suppress this lint if you plan to use the trait locally, for concrete types, or do not care about auto traits like `Send` on the `Future`
+    .suggestion = you can alternatively desugar to a normal `fn` that returns `impl Future` and add any desired bounds such as `Send`
 
 lint_atomic_ordering_fence = memory fences cannot have `Relaxed` ordering
     .help = consider using ordering modes `Acquire`, `Release`, `AcqRel` or `SeqCst`

Diff for: compiler/rustc_lint/src/async_fn_in_trait.rs

@@ -5,26 +5,85 @@ use rustc_hir as hir;
 use rustc_trait_selection::traits::error_reporting::suggestions::suggest_desugaring_async_fn_to_impl_future_in_trait;
 
 declare_lint! {
-    /// TODO
+    /// The `async_fn_in_trait` lint detects use of `async fn` in the
+    /// definition of a publicly-reachable trait.
     ///
     /// ### Example
     ///
     /// ```rust
-    /// fn foo<T: Drop>() {}
+    /// # #![feature(async_fn_in_trait)]
+    /// pub trait Trait {
+    ///     async fn method(&self);
+    /// }
     /// ```
     ///
     /// {{produces}}
     ///
     /// ### Explanation
     ///
-    /// TODO
+    /// When `async fn` is used in a trait definition, the trait does not
+    /// promise that the opaque [`Future`] returned by the associated function
+    /// or method will implement any [auto traits] such as [`Send`]. This may
+    /// be surprising and may make the associated functions or methods on the
+    /// trait less useful than intended. On traits exposed publicly from a
+    /// crate, this may affect downstream crates whose authors cannot alter
+    /// the trait definition.
+    ///
+    /// For example, this code is invalid:
+    ///
+    /// ```rust,compile_fail
+    /// # #![feature(async_fn_in_trait)]
+    /// pub trait Trait {
+    ///     async fn method(&self) {}
+    /// }
+    ///
+    /// fn test<T: Trait>(x: T) {
+    ///     fn is_send<T: Send>(_: T) {}
+    ///     is_send(x.method()); // Not OK.
+    /// }
+    /// ```
+    ///
+    /// This lint exists to warn authors of publicly-reachable traits that
+    /// they may want to consider desugaring the `async fn` to a normal `fn`
+    /// that returns an opaque `impl Future<..> + Send` type.
+    ///
+    /// For example, instead of:
+    ///
+    /// ```rust
+    /// # #![feature(async_fn_in_trait)]
+    /// pub trait Trait {
+    ///     async fn method(&self) {}
+    /// }
+    /// ```
+    ///
+    /// The author of the trait may want to write:
+    ///
+    ///
+    /// ```rust
+    /// # #![feature(return_position_impl_trait_in_trait)]
+    /// use core::future::Future;
+    /// pub trait Trait {
+    ///     fn method(&self) -> impl Future<Output = ()> + Send { async {} }
+    /// }
+    /// ```
+    ///
+    /// Conversely, if the trait is used only locally, if only concrete types
+    /// that implement the trait are used, or if the trait author otherwise
+    /// does not care that the trait will not promise that the returned
+    /// [`Future`] implements any [auto traits] such as [`Send`], then the
+    /// lint may be suppressed.
+    ///
+    /// [`Future`]: https://doc.rust-lang.org/core/future/trait.Future.html
+    /// [`Send`]: https://doc.rust-lang.org/core/marker/trait.Send.html
+    /// [auto traits]: https://doc.rust-lang.org/reference/special-types-and-traits.html#auto-traits
     pub ASYNC_FN_IN_TRAIT,
     Warn,
-    "TODO"
+    "use of `async fn` in definition of a publicly-reachable trait"
 }
 
 declare_lint_pass!(
-    // TODO:
+    /// Lint for use of `async fn` in the definition of a publicly-reachable
+    /// trait.
     AsyncFnInTrait => [ASYNC_FN_IN_TRAIT]
 );