From 2232e7e2723852a06a8262ca39f84d3863f5be6d Mon Sep 17 00:00:00 2001
From: Damien L-G <dalg24@gmail.com>
Date: Wed, 16 Oct 2024 10:15:40 -0400
Subject: [PATCH] Improve atomic_{load,store} documentation

---
 docs/source/API/core/atomics/atomic_load.rst  | 19 +++++++++++-------
 docs/source/API/core/atomics/atomic_store.rst | 20 ++++++++++++-------
 2 files changed, 25 insertions(+), 14 deletions(-)

diff --git a/docs/source/API/core/atomics/atomic_load.rst b/docs/source/API/core/atomics/atomic_load.rst
index 2d3956a18..6d5f90032 100644
--- a/docs/source/API/core/atomics/atomic_load.rst
+++ b/docs/source/API/core/atomics/atomic_load.rst
@@ -4,22 +4,27 @@
 .. role:: cppkokkos(code)
     :language: cppkokkos
 
-Header File: ``<Kokkos_Core.hpp>``
+Defined in header ``<Kokkos_Atomic.hpp>`` which is included from ``<Kokkos_Core.hpp>``
 
 Usage
 -----
 
 .. code-block:: cpp
 
-    value = atomic_load(ptr_to_value);
+    auto current = atomic_load(&obj);
 
-Atomically reads the value at the address given by ``ptr_to_value``.
+Atomically obtains ``obj``'s value.
 
 Description
 -----------
 
-.. cppkokkos:function:: template<class T> T atomic_load(T* const ptr_to_value);
+.. cppkokkos:function:: template<class T> T atomic_load(T* ptr);
 
-Atomically executes ``value = *ptr_to_value; return value;``. 
-    * ``ptr_to_value``: address of the to be updated value.
-    * ``value``: value at address ``ptr_to_value``.
+   Atomically reads the content of ``*ptr`` and returns it (``T val = *ptr; return val;``). 
+
+   - ``ptr``: address of the object whose current value is to be returned.
+
+See also
+--------
+* `atomic_store <atomic_store.html>`_: atomically replaces the value of the referenced object with a non-atomic argument
+* `atomic_exchange <atomic_exchange.html>`_: atomically replaces the value of the referenced object and obtains the value held previously
diff --git a/docs/source/API/core/atomics/atomic_store.rst b/docs/source/API/core/atomics/atomic_store.rst
index 1c62a107a..da9a6c420 100644
--- a/docs/source/API/core/atomics/atomic_store.rst
+++ b/docs/source/API/core/atomics/atomic_store.rst
@@ -4,24 +4,30 @@
 .. role:: cppkokkos(code)
     :language: cppkokkos
 
-Header File: ``<Kokkos_Core.hpp>``
+Defined in header ``<Kokkos_Atomic.hpp>`` which is included from ``<Kokkos_Core.hpp>``
 
 Usage
 -----
 
 .. code-block:: cpp
 
-    atomic_store(ptr_to_value,new_value);
+    atomic_store(&obj, desired);
 
-Atomically sets the value at the address given by ``ptr_to_value`` to ``new_value``.
+Atomically replaces ``obj``'s value with ``desired``.
 
 Description
 -----------
 
-.. cppkokkos:function:: template<class T> void atomic_store(T* const ptr_to_value, const T new_value);
+.. cppkokkos:function:: template<class T> void atomic_store(T* ptr, std::identity_type_t<T> val);
 
-   Atomically executes ``*ptr_to_value = new_value;``.
+   Atomically writes ``val`` into ``*ptr`` (``*ptr = val;``).
 
-   - ``ptr_to_value``: address of the to be updated value.
+   - ``ptr``: address of the object whose value is to be replaced.
 
-   - ``new_value``: new value.
+   - ``val``: value to store in the referenced object.
+
+
+See also
+--------
+* `atomic_load <atomic_load.html>`_: atomically obtains the value of the referenced object
+* `atomic_exchange <atomic_exchange.html>`_: atomically replaces the value of the referenced object and obtains the value held previously