From eca4fb5bc0abd2c0a04036ef8cb70ca7a869b1c4 Mon Sep 17 00:00:00 2001
From: Damien L-G <dalg24@gmail.com>
Date: Mon, 11 Nov 2024 16:30:36 -0500
Subject: [PATCH] Document atomic_assign (#595)

* Fix typo retur[n]s

* Document atomic_assign

* Fiddle with atomics TOC

* Remove old doc for atomic_assign
---
 docs/source/API/core/atomics.rst              |  7 ++--
 .../source/API/core/atomics/atomic_assign.rst | 37 +++++++++++++++++++
 .../API/core/atomics/atomic_exchange.rst      |  2 +-
 docs/source/API/core/atomics/atomic_op.rst    |  8 ----
 4 files changed, 42 insertions(+), 12 deletions(-)
 create mode 100644 docs/source/API/core/atomics/atomic_assign.rst

diff --git a/docs/source/API/core/atomics.rst b/docs/source/API/core/atomics.rst
index fd2843bb6..fe8ea4e82 100644
--- a/docs/source/API/core/atomics.rst
+++ b/docs/source/API/core/atomics.rst
@@ -4,11 +4,12 @@ Atomics
 .. toctree::
    :maxdepth: 1
 
+   ./atomics/atomic_load
+   ./atomics/atomic_store
+   ./atomics/atomic_exchange
    ./atomics/atomic_compare_exchange
    ./atomics/atomic_compare_exchange_strong
-   ./atomics/atomic_exchange
+   ./atomics/atomic_assign
    ./atomics/atomic_fetch_op
-   ./atomics/atomic_load
    ./atomics/atomic_op
    ./atomics/atomic_op_fetch
-   ./atomics/atomic_store
diff --git a/docs/source/API/core/atomics/atomic_assign.rst b/docs/source/API/core/atomics/atomic_assign.rst
new file mode 100644
index 000000000..d677bea23
--- /dev/null
+++ b/docs/source/API/core/atomics/atomic_assign.rst
@@ -0,0 +1,37 @@
+``atomic_assign``
+=================
+
+.. warning::
+   Deprecated since Kokkos 4.5,
+   use `atomic_store <atomic_store.html>`_ instead.
+
+.. role:: cppkokkos(code)
+    :language: cppkokkos
+
+Defined in header ``<Kokkos_Atomic.hpp>`` which is included from ``<Kokkos_Core.hpp>``
+
+Usage
+-----
+
+.. code-block:: cpp
+
+    atomic_assign(&obj, desired);
+    //     ^^^^^^
+    // deprecated since Kokkos 4.5,
+    // use atomic_store(&obj, desired) instead
+
+Atomically replaces the current value of ``obj`` with ``desired``.
+
+Description
+-----------
+
+.. cppkokkos:function:: template<class T> void atomic_assign(T* ptr, std::type_identity_t<T> val);
+
+   Atomically writes ``val`` into ``*ptr``.
+
+   ``{ *ptr = val; }``
+
+   :param ptr: address of the object whose value is to be replaced
+   :param val: the value to store in the referenced object
+   :returns: (nothing)
+
diff --git a/docs/source/API/core/atomics/atomic_exchange.rst b/docs/source/API/core/atomics/atomic_exchange.rst
index 6095c9592..ebae4597f 100644
--- a/docs/source/API/core/atomics/atomic_exchange.rst
+++ b/docs/source/API/core/atomics/atomic_exchange.rst
@@ -13,7 +13,7 @@ Usage
 
    auto old = atomic_exchange(&obj, desired);
 
-Atomically replaces the value of ``obj`` with ``desired`` and returs the value before the call.
+Atomically replaces the value of ``obj`` with ``desired`` and returns the value before the call.
 
 Description
 -----------
diff --git a/docs/source/API/core/atomics/atomic_op.rst b/docs/source/API/core/atomics/atomic_op.rst
index acc02631a..4a04cdd7d 100644
--- a/docs/source/API/core/atomics/atomic_op.rst
+++ b/docs/source/API/core/atomics/atomic_op.rst
@@ -34,14 +34,6 @@ Description
 
    * ``value``: value with which to combine the original value.
 
-.. cppkokkos:function:: template<class T> void atomic_assign(T* const ptr_to_value, const T value);
-
-   Atomically executes ``*ptr_to_value = value``.
-
-   * ``ptr_to_value``: address of the to be updated value.
-
-   * ``value``: new value.
-
 .. cppkokkos:function:: template<class T> void atomic_decrement(T* const ptr_to_value);
 
    Atomically executes ``(*ptr_to_value)--`` or calls ``atomic_fetch_sub(ptr_to_value, T(-1))``.