From 8758965206d3c23c07ded0518d6c7398043ef227 Mon Sep 17 00:00:00 2001
From: Eliza Weisman <eliza@buoyant.io>
Date: Tue, 15 Feb 2022 09:57:06 -0800
Subject: [PATCH] task: fix unstable API documentation notes (#4503)

## Motivation

PR #4499 made the `JoinSet` API unstable, but did not add a
documentation note explaining unstable features. In general, since the
docs.rs build includes unstable APIs, it's probably worth including
these notes so that users understand what it means for an API to be
unstable.

## Solution

This branch adds a note on unstable APIs to the `JoinSet` type-level
documentation, similar to the notes for `task::Builder` and the runtime
metrics APIs.

Also, I noticed that there was a broken link to the top-level
documentation on unstable APIs in the docs for `task::Builder`, so I
fixed that as well.
---
 tokio/src/task/builder.rs  | 2 +-
 tokio/src/task/join_set.rs | 6 ++++++
 2 files changed, 7 insertions(+), 1 deletion(-)

diff --git a/tokio/src/task/builder.rs b/tokio/src/task/builder.rs
index 5a128420ee2..2086302fb92 100644
--- a/tokio/src/task/builder.rs
+++ b/tokio/src/task/builder.rs
@@ -49,7 +49,7 @@ use std::future::Future;
 ///     }
 /// }
 /// ```
-/// [unstable API]: crate#unstable-features
+/// [unstable]: crate#unstable-features
 /// [`name`]: Builder::name
 /// [`spawn_local`]: Builder::spawn_local
 /// [`spawn`]: Builder::spawn
diff --git a/tokio/src/task/join_set.rs b/tokio/src/task/join_set.rs
index 3c5de553ebe..8e8f74f66d1 100644
--- a/tokio/src/task/join_set.rs
+++ b/tokio/src/task/join_set.rs
@@ -17,6 +17,10 @@ use crate::util::IdleNotifiedSet;
 ///
 /// When the `JoinSet` is dropped, all tasks in the `JoinSet` are immediately aborted.
 ///
+/// **Note**: This is an [unstable API][unstable]. The public API of this type
+/// may break in 1.x releases. See [the documentation on unstable
+/// features][unstable] for details.
+///
 /// # Examples
 ///
 /// Spawn multiple tasks and wait for them.
@@ -42,6 +46,8 @@ use crate::util::IdleNotifiedSet;
 ///     }
 /// }
 /// ```
+///
+/// [unstable]: crate#unstable-features
 pub struct JoinSet<T> {
     inner: IdleNotifiedSet<JoinHandle<T>>,
 }