From 5dcc418f62e14580a319b2b8ec24645abbc1569e Mon Sep 17 00:00:00 2001
From: Kevin Reid <kpreid@google.com>
Date: Fri, 17 Jun 2022 19:46:01 -0700
Subject: [PATCH] Document the conditional existence of `alloc::sync` and
 `alloc::task`.

The wording is copied from `std::sync::atomic::AtomicPtr`, with
additional advice on how to `#[cfg]` for it.
---
 library/alloc/src/sync.rs | 9 +++++++++
 library/alloc/src/task.rs | 6 ++++++
 2 files changed, 15 insertions(+)

diff --git a/library/alloc/src/sync.rs b/library/alloc/src/sync.rs
index 55d51e0a3c4cf..d91217f341abd 100644
--- a/library/alloc/src/sync.rs
+++ b/library/alloc/src/sync.rs
@@ -3,6 +3,10 @@
 //! Thread-safe reference-counting pointers.
 //!
 //! See the [`Arc<T>`][Arc] documentation for more details.
+//!
+//! **Note**: This module is only available on platforms that support atomic
+//! loads and stores of pointers. This may be detected at compile time using
+//! `#[cfg(target_has_atomic = "ptr")]`.
 
 use core::any::Any;
 use core::borrow;
@@ -82,6 +86,11 @@ macro_rules! acquire {
 /// [`Mutex`][mutex], [`RwLock`][rwlock], or one of the [`Atomic`][atomic]
 /// types.
 ///
+/// **Note**: This type is only available on platforms that support atomic
+/// loads and stores of pointers, which includes all platforms that support
+/// the `std` crate but not all those which only support [`alloc`](crate).
+/// This may be detected at compile time using `#[cfg(target_has_atomic = "ptr")]`.
+///
 /// ## Thread Safety
 ///
 /// Unlike [`Rc<T>`], `Arc<T>` uses atomic operations for its reference
diff --git a/library/alloc/src/task.rs b/library/alloc/src/task.rs
index 528ee4ff1542c..9d8e309a978d9 100644
--- a/library/alloc/src/task.rs
+++ b/library/alloc/src/task.rs
@@ -1,5 +1,11 @@
 #![stable(feature = "wake_trait", since = "1.51.0")]
+
 //! Types and Traits for working with asynchronous tasks.
+//!
+//! **Note**: This module is only available on platforms that support atomic
+//! loads and stores of pointers. This may be detected at compile time using
+//! `#[cfg(target_has_atomic = "ptr")]`.
+
 use core::mem::ManuallyDrop;
 use core::task::{RawWaker, RawWakerVTable, Waker};