Miscellaneous documentation fixes and updates

.github/workflows/docs.yml

@@ -33,8 +33,11 @@ jobs:
                 --allow-downgrades \
                 --allow-remove-essential \
                 --allow-change-held-packages \
-                doxygen python3 python3-pip
+                doxygen python3 python3-pip ripgrep
             pip install --requirement $PWD/docs/requirements.txt
+      - name: Check that docstrings don't use @command
+        run: |
+            ./scripts/check_doxygen_commands.sh $PWD
       - name: Build documentation
         run: |
             export PIKA_DOCS_DOXYGEN_OUTPUT_DIRECTORY=$PWD/build/doxygen

docs/api.rst

@@ -33,7 +33,6 @@ These headers are part of the public API, but are currently undocumented.
 - ``pika/barrier.hpp``
 - ``pika/condition_variable.hpp``
 - ``pika/cuda.hpp``
-- ``pika/execution.hpp``
 - ``pika/latch.hpp``
 - ``pika/mpi.hpp``
 - ``pika/mutex.hpp``

docs/index.rst

@@ -10,8 +10,8 @@ Overview
 ========
 
 **pika** is a C++ library that builds on the `std::execution (P2300) proposal
-<https://wg21.link/p2300>`__ by providing a CPU runtime with user-level threads, as well as
-integration with CUDA, HIP, and MPI. See :ref:`getting_started` to get started.
+<https://wg21.link/p2300>`__ accepted to C++26 by providing a CPU runtime with user-level threads,
+as well as integration with CUDA, HIP, and MPI. See :ref:`getting_started` to get started.
 
 Hello, world
 ============

docs/usage.rst

@@ -45,7 +45,7 @@ If you'd like to build pika manually you will need CMake 3.22.0 or greater and a
 supporting C++17:
 
 - `GCC <https://gcc.gnu.org>`__ 9 or greater
-- `clang <https://clang.llvm.org>`__ 11 or greater
+- `clang <https://clang.llvm.org>`__ 13 or greater
 
 Additionally, pika depends on:
 

examples/documentation/hello_world_documentation.cpp

@@ -8,10 +8,8 @@
 #include <pika/init.hpp>
 #include <pika/thread.hpp>
 
-#include <fmt/ostream.h>
 #include <fmt/printf.h>
 
-#include <iostream>
 #include <utility>
 
 int main(int argc, char* argv[])
@@ -30,7 +28,7 @@ int main(int argc, char* argv[])
 
     // We can schedule work using sched.
     auto snd1 = ex::just(42) | ex::continues_on(sched) | ex::then([](int x) {
-        fmt::print(std::cout, "Hello from a pika user-level thread (with id {})!\nx = {}\n",
+        fmt::print("Hello from a pika user-level thread (with id {})!\nx = {}\n",
             pika::this_thread::get_id(), x);
     });
 
@@ -40,11 +38,11 @@ int main(int argc, char* argv[])
     // We can build arbitrary graphs of work using the split and when_all adaptors.
     auto snd2 = ex::just(3.14) | ex::split();
     auto snd3 = ex::continues_on(snd2, sched) |
-        ex::then([](double pi) { fmt::print(std::cout, "Is this pi: {}?\n", pi); });
+        ex::then([](double pi) { fmt::print("Is this pi: {}?\n", pi); });
     auto snd4 = ex::when_all(std::move(snd2), ex::just(500.3)) | ex::continues_on(sched) |
         ex::then([](double pi, double r) { return pi * r * r; });
     auto result = tt::sync_wait(ex::when_all(std::move(snd3), std::move(snd4)));
-    fmt::print(std::cout, "The result is {}\n", result);
+    fmt::print("The result is {}\n", result);
 
     // Tell the runtime that when there are no more tasks in the queues it is ok to stop.
     pika::finalize();

examples/documentation/init_hpp_documentation.cpp

@@ -9,15 +9,19 @@
 
 #include <fmt/printf.h>
 
+#include <utility>
+
 int main(int argc, char* argv[])
 {
+    namespace ex = pika::execution::experimental;
+    namespace tt = pika::this_thread::experimental;
+
     pika::start(argc, argv);
 
     // The pika runtime is now active and we can schedule work on the default thread pool
-    pika::this_thread::experimental::sync_wait(
-        pika::execution::experimental::schedule(
-            pika::execution::experimental::thread_pool_scheduler{}) |
-        pika::execution::experimental::then([]() { fmt::print("Hello from the pika runtime\n"); }));
+    auto s = ex::schedule(ex::thread_pool_scheduler{}) |
+        ex::then([]() { fmt::print("Hello from the pika runtime\n"); });
+    tt::sync_wait(std::move(s));
 
     pika::finalize();
     pika::stop();

libs/pika/async_cuda/tests/unit/cublas_matmul.cpp

@@ -67,11 +67,11 @@ struct sMatrixSize
 // -------------------------------------------------------------------------
 // Compute reference data set matrix multiply on CPU
 // C = A * B
-// @param C          reference data, computed but preallocated
-// @param A          matrix A as provided to device
-// @param B          matrix B as provided to device
-// @param hA         height of matrix A
-// @param wB         width of matrix B
+// \param C          reference data, computed but preallocated
+// \param A          matrix A as provided to device
+// \param B          matrix B as provided to device
+// \param hA         height of matrix A
+// \param wB         width of matrix B
 // -------------------------------------------------------------------------
 template <typename T>
 void matrixMulCPU(T* C, T const* A, T const* B, unsigned int hA, unsigned int wA, unsigned int wB)

libs/pika/coroutines/include/pika/coroutines/detail/context_linux_x86.hpp

@@ -133,9 +133,9 @@ namespace pika::threads::coroutines {
             }
 
             /**
-             * Free function. Saves the current context in @p from
-             * and restores the context in @p to.
-             * @note This function is found by ADL.
+             * Free function. Saves the current context in \p from
+             * and restores the context in \p to.
+             * \note This function is found by ADL.
              */
             friend void swap_context(x86_linux_context_impl_base& from,
                 x86_linux_context_impl_base const& to, default_hint);
@@ -472,9 +472,9 @@ namespace pika::threads::coroutines {
         };
 
         /**
-         * Free function. Saves the current context in @p from
-         * and restores the context in @p to.
-         * @note This function is found by ADL.
+         * Free function. Saves the current context in \p from
+         * and restores the context in \p to.
+         * \note This function is found by ADL.
          */
         inline void swap_context(
             x86_linux_context_impl_base& from, x86_linux_context_impl_base const& to, default_hint)

libs/pika/coroutines/include/pika/coroutines/detail/context_posix.hpp

@@ -174,7 +174,7 @@ namespace pika::threads::coroutines {
 
     namespace detail::posix {
         /// Posix implementation for the context_impl_base class.
-        /// @note context_impl is not required to be consistent
+        /// \note context_impl is not required to be consistent
         /// If not initialized it can only be swapped out, not in
         /// (at that point it will be initialized).
         class ucontext_context_impl_base : detail::context_impl_base
@@ -209,8 +209,8 @@ namespace pika::threads::coroutines {
 # endif
 
         private:
-            /// Free function. Saves the current context in @p from
-            /// and restores the context in @p to.
+            /// Free function. Saves the current context in \p from
+            /// and restores the context in \p to.
             friend void swap_context(ucontext_context_impl_base& from,
                 ucontext_context_impl_base const& to, default_hint)
             {

libs/pika/coroutines/include/pika/coroutines/detail/context_windows_fibers.hpp

@@ -102,7 +102,7 @@ namespace pika::threads::coroutines {
 
         /*
          * Windows implementation for the context_impl_base class.
-         * @note context_impl is not required to be consistent
+         * \note context_impl is not required to be consistent
          * If not initialized it can only be swapped out, not in
          * (at that point it will be initialized).
          */
@@ -125,8 +125,8 @@ namespace pika::threads::coroutines {
             }
 
             /*
-             * Free function. Saves the current context in @p from
-             * and restores the context in @p to. On windows the from
+             * Free function. Saves the current context in \p from
+             * and restores the context in \p to. On windows the from
              * parameter is ignored. The current context is saved on the
              * current fiber.
              * Note that if the current thread is not a fiber, it will be

libs/pika/coroutines/include/pika/coroutines/detail/posix_utility.hpp

@@ -231,7 +231,7 @@ namespace pika::threads::coroutines::detail::posix {
 
     /**
      * The splitter is needed for 64 bit systems.
-     * @note The current implementation does NOT use
+     * \note The current implementation does NOT use
      * (for debug reasons).
      * Thus it is not 64 bit clean.
      * Use it for 64 bits systems.

libs/pika/execution/include/pika/execution/algorithms/drop_operation_state.hpp

@@ -259,7 +259,7 @@ namespace pika::execution::experimental {
     ///
     /// The operation state of previous senders can hold on to allocated memory or values longer
     /// than necessary which can prevent other algorithms from using those resources.
-    /// @p drop_operation_state can be used to explicitly release the operation state, and thus
+    /// \p drop_operation_state can be used to explicitly release the operation state, and thus
     /// associated resources, of previous senders.
     ///
     /// Added in 0.19.0.

libs/pika/init_runtime/include/pika/init_runtime/init_runtime.hpp

@@ -85,109 +85,109 @@ namespace pika {
     PIKA_EXPORT int init(std::nullptr_t, int argc, char const* const* argv,
         init_params const& params = init_params());
 
-    /// @brief Start the runtime.
+    /// \brief Start the runtime.
     ///
-    /// @param f entry point of the first task on the pika runtime. f will be passed all non-pika
+    /// \param f entry point of the first task on the pika runtime. f will be passed all non-pika
     /// command line arguments.
-    /// @param argc number of arguments in argv
-    /// @param argv array of arguments. The first element is ignored.
+    /// \param argc number of arguments in argv
+    /// \param argv array of arguments. The first element is ignored.
     ///
-    /// @pre `(argc == 0 && argv == nullptr) || (argc >= 1 && argv != nullptr)`
-    /// @pre the runtime is stopped
-    /// @post the runtime is running
+    /// \pre `(argc == 0 && argv == nullptr) || (argc >= 1 && argv != nullptr)`
+    /// \pre the runtime is stopped
+    /// \post the runtime is running
     PIKA_EXPORT void start(std::function<int(pika::program_options::variables_map&)> f, int argc,
         char const* const* argv, init_params const& params = init_params());
 
-    /// @brief Start the runtime.
+    /// \brief Start the runtime.
     ///
-    /// @param f entry point of the first task on the pika runtime. f will be passed all non-pika
+    /// \param f entry point of the first task on the pika runtime. f will be passed all non-pika
     /// command line arguments.
-    /// @param argc number of arguments in argv
-    /// @param argv array of arguments. The first element is ignored.
+    /// \param argc number of arguments in argv
+    /// \param argv array of arguments. The first element is ignored.
     ///
-    /// @pre `(argc == 0 && argv == nullptr) || (argc >= 1 && argv != nullptr)`
-    /// @pre the runtime is stopped
-    /// @post the runtime is running
+    /// \pre `(argc == 0 && argv == nullptr) || (argc >= 1 && argv != nullptr)`
+    /// \pre the runtime is stopped
+    /// \post the runtime is running
     PIKA_EXPORT void start(std::function<int(int, char**)> f, int argc, char const* const* argv,
         init_params const& params = init_params());
 
-    /// @brief Start the runtime.
+    /// \brief Start the runtime.
     ///
-    /// @param f entry point of the first task on the pika runtime
-    /// @param argc number of arguments in argv
-    /// @param argv array of arguments. The first element is ignored.
+    /// \param f entry point of the first task on the pika runtime
+    /// \param argc number of arguments in argv
+    /// \param argv array of arguments. The first element is ignored.
     ///
-    /// @pre `(argc == 0 && argv == nullptr) || (argc >= 1 && argv != nullptr)`
-    /// @pre the runtime is not running
+    /// \pre `(argc == 0 && argv == nullptr) || (argc >= 1 && argv != nullptr)`
+    /// \pre the runtime is not running
     PIKA_EXPORT void start(std::function<int()> f, int argc, char const* const* argv,
         init_params const& params = init_params());
 
     PIKA_EXPORT void start(std::nullptr_t, int argc, char const* const* argv,
         init_params const& params = init_params());
 
-    /// @brief Start the runtime.
+    /// \brief Start the runtime.
     ///
     /// No task is created on the runtime.
     ///
-    /// @param argc number of arguments in argv
-    /// @param argv array of arguments. The first element is ignored.
+    /// \param argc number of arguments in argv
+    /// \param argv array of arguments. The first element is ignored.
     ///
-    /// @pre `(argc == 0 && argv == nullptr) || (argc >= 1 && argv != nullptr)`
-    /// @pre the runtime is not initialized
-    /// @post the runtime is running
+    /// \pre `(argc == 0 && argv == nullptr) || (argc >= 1 && argv != nullptr)`
+    /// \pre the runtime is not initialized
+    /// \post the runtime is running
     PIKA_EXPORT void start(
         int argc, char const* const* argv, init_params const& params = init_params());
 
-    /// @brief Stop the runtime.
+    /// \brief Stop the runtime.
     ///
-    /// Waits until @ref pika::finalize() has been called and there is no more activity on the
-    /// runtime. See @ref pika::wait(). The runtime can be started again after calling @ref
+    /// Waits until \ref pika::finalize() has been called and there is no more activity on the
+    /// runtime. See \ref pika::wait(). The runtime can be started again after calling \ref
     /// pika::stop(). Must be called from outside the runtime.
     ///
-    /// @return the return value of the callable passed to @ref pika::start(int, char const* const*,
+    /// \return the return value of the callable passed to \ref pika::start(int, char const* const*,
     /// init_params const&)", if any. If none was passed, returns 0.
     ///
-    /// @pre the runtime is initialized
-    /// @pre the calling thread is not a pika task
-    /// @post the runtime is not initialized
+    /// \pre the runtime is initialized
+    /// \pre the calling thread is not a pika task
+    /// \post the runtime is not initialized
     PIKA_EXPORT int stop();
 
-    /// @brief Signal the runtime that it may be stopped.
+    /// \brief Signal the runtime that it may be stopped.
     ///
-    /// Until @ref pika::finalize() has been called, @ref pika::stop() will not return. This
+    /// Until \ref pika::finalize() has been called, \ref pika::stop() will not return. This
     /// function exists to distinguish between the runtime being idle but still expecting work to be
-    /// scheduled on it and the runtime being idle and ready to be shutdown. Unlike @ref
-    /// pika::stop(), @ref pika::finalize() can be called from within or outside the runtime.
+    /// scheduled on it and the runtime being idle and ready to be shutdown. Unlike \ref
+    /// pika::stop(), \ref pika::finalize() can be called from within or outside the runtime.
     ///
-    /// @pre the runtime is initialized
+    /// \pre the runtime is initialized
     PIKA_EXPORT void finalize();
 
-    /// @brief Wait for the runtime to be idle.
+    /// \brief Wait for the runtime to be idle.
     ///
     /// Waits until the runtime is idle. This includes tasks scheduled on the thread pools as well
     /// as non-tasks such as CUDA kernels submitted through pika facilities. Can be called from
     /// within the runtime, in which case the calling task is ignored when determining idleness.
     ///
-    /// @pre the runtime is initialized
-    /// @post all work submitted before the call to wait is completed
+    /// \pre the runtime is initialized
+    /// \post all work submitted before the call to wait is completed
     PIKA_EXPORT void wait();
 
-    /// @brief Suspend the runtime.
+    /// \brief Suspend the runtime.
     ///
     /// Waits until the runtime is idle and suspends worker threads on all thread pools. Work can be
     /// scheduled on the runtime even when it is suspended, but no progress will be made.
     ///
-    /// @pre the calling thread is not a pika task
-    /// @pre runtime is running or suspended
-    /// @post runtime is suspended
+    /// \pre the calling thread is not a pika task
+    /// \pre runtime is running or suspended
+    /// \post runtime is suspended
     PIKA_EXPORT void suspend();
 
-    /// @brief Resume the runtime.
+    /// \brief Resume the runtime.
     ///
     /// Resumes the runtime by waking all worker threads on all thread pools.
     ///
-    /// @pre the calling thread is not a pika task
-    /// @pre runtime is suspended or running
-    /// @post runtime is running
+    /// \pre the calling thread is not a pika task
+    /// \pre runtime is suspended or running
+    /// \post runtime is running
     PIKA_EXPORT void resume();
 }    // namespace pika

libs/pika/program_options/include/pika/program_options/detail/value_semantic.hpp

@@ -79,7 +79,7 @@ namespace pika::program_options {
     using namespace validators;
 
     /** Validates 's' and updates 'v'.
-        @pre 'v' is either empty or in the state assigned by the previous
+        \pre 'v' is either empty or in the state assigned by the previous
         invocation of 'validate'.
         The target type is specified via a parameter which has the type of
         pointer to the desired type. This is workaround for compilers without

libs/pika/program_options/include/pika/program_options/options_description.hpp

@@ -167,7 +167,7 @@ namespace pika::program_options {
         adding new option (the add_options) method, and facilities to search
         for options by name.
 
-        See @ref a_adding_options "here" for option adding interface discussion.
+        See \ref a_adding_options "here" for option adding interface discussion.
         @sa option_description
     */
     class PIKA_EXPORT options_description

libs/pika/runtime/include/pika/runtime/runtime.hpp

@@ -437,10 +437,10 @@ namespace pika::detail {
 }    // namespace pika::detail
 
 namespace pika {
-    /// @brief Returns true when the runtime is initialized, false otherwise.
+    /// \brief Returns true when the runtime is initialized, false otherwise.
     ///
-    /// Returns true between calls of @ref pika::start(int, char const* const*, init_params const&)
-    /// and @ref pika::stop(), otherwise false.
+    /// Returns true between calls of \ref pika::start(int, char const* const*, init_params const&)
+    /// and \ref pika::stop(), otherwise false.
     ///
     /// Added in 0.22.0.
     PIKA_EXPORT bool is_runtime_initialized() noexcept;

libs/pika/runtime/include/pika/runtime/runtime_fwd.hpp

@@ -53,8 +53,6 @@ namespace pika::detail {
     ///////////////////////////////////////////////////////////////////////////
     PIKA_EXPORT pika::util::runtime_configuration const& get_config();
 
-    /// \endcond
-
     ///////////////////////////////////////////////////////////////////////////
     /// \brief Test whether the runtime system is currently being started.
     ///