From 70dcff47e04b8c131be39cdd2e5d8f2032ec8454 Mon Sep 17 00:00:00 2001 From: Eric Niebler Date: Tue, 2 Jun 2026 11:28:18 -0700 Subject: [PATCH] correct all C++ stable section names mentioned in the source --- docs/CMakeLists.txt | 4 +++ docs/CONTRIBUTING-docs.md | 6 +++++ docs/Doxyfile.in | 2 +- include/exec/ensure_started.hpp | 1 - include/exec/execute.hpp | 1 - include/exec/on.hpp | 2 +- include/exec/sequence_senders.hpp | 1 - include/exec/split.hpp | 1 - include/exec/start_detached.hpp | 1 - include/stdexec/__detail/__bulk.hpp | 2 +- include/stdexec/__detail/__connect.hpp | 2 +- include/stdexec/__detail/__continues_on.hpp | 2 +- include/stdexec/__detail/__into_variant.hpp | 2 +- include/stdexec/__detail/__just.hpp | 2 +- include/stdexec/__detail/__on.hpp | 2 +- .../stdexec/__detail/__operation_states.hpp | 4 +-- include/stdexec/__detail/__queries.hpp | 2 +- include/stdexec/__detail/__receivers.hpp | 2 +- include/stdexec/__detail/__schedule_from.hpp | 2 +- .../stdexec/__detail/__sender_concepts.hpp | 27 ++++++++++--------- .../stdexec/__detail/__stopped_as_error.hpp | 2 +- .../__detail/__stopped_as_optional.hpp | 2 +- include/stdexec/__detail/__sync_wait.hpp | 6 ++--- include/stdexec/__detail/__then.hpp | 2 +- include/stdexec/__detail/__transfer_just.hpp | 1 - .../stdexec/__detail/__transform_sender.hpp | 4 +-- include/stdexec/__detail/__upon_error.hpp | 2 +- include/stdexec/__detail/__upon_stopped.hpp | 2 +- include/stdexec/__detail/__when_all.hpp | 3 +-- 29 files changed, 49 insertions(+), 43 deletions(-) diff --git a/docs/CMakeLists.txt b/docs/CMakeLists.txt index bccb3f8eb..5645aac99 100644 --- a/docs/CMakeLists.txt +++ b/docs/CMakeLists.txt @@ -38,6 +38,10 @@ set(DOXYGEN_INDEX_FILE ${DOXYGEN_OUTPUT_DIR}/xml/index.xml) set(DOXYFILE_IN ${CMAKE_CURRENT_SOURCE_DIR}/Doxyfile.in) set(DOXYFILE_OUT ${CMAKE_CURRENT_BINARY_DIR}/Doxyfile) +# Doxygen INPUT_FILTER that hyperlinks [exec.*] working-draft stable names in +# the comments to the corresponding sections on https://eel.is/c++draft. +set(DOXYGEN_INPUT_FILTER "perl ${CMAKE_CURRENT_SOURCE_DIR}/eelis_link_filter.pl") + # Find the location of stddef.h execute_process(COMMAND echo "#include " COMMAND c++ -xc -dI -E - diff --git a/docs/CONTRIBUTING-docs.md b/docs/CONTRIBUTING-docs.md index d399e49de..8dc7d7c6a 100644 --- a/docs/CONTRIBUTING-docs.md +++ b/docs/CONTRIBUTING-docs.md @@ -58,6 +58,12 @@ both call syntaxes (direct and pipe) in a small `@code{.cpp}` block. End with a pointer to the normative spec: `See [exec.foo] in the C++26 working draft for the normative specification.` +Use the exact working-draft stable name in brackets (e.g. `[exec.then]`, +`[exec.sync.wait.var]`). A Doxygen input filter (`eelis_link_filter.pl`) +automatically turns any `[exec.*]` reference into a hyperlink to the matching +section on in the generated docs, so just write the +bare stable name — do not add the URL by hand. + ### 3. Inline section headings Use **bold inline headings** for sub-sections — not `@par`, not `###`. diff --git a/docs/Doxyfile.in b/docs/Doxyfile.in index b3453c8e8..ba8046832 100644 --- a/docs/Doxyfile.in +++ b/docs/Doxyfile.in @@ -1098,7 +1098,7 @@ IMAGE_PATH = # need to set EXTENSION_MAPPING for the extension otherwise the files are not # properly processed by doxygen. -INPUT_FILTER = +INPUT_FILTER = "@DOXYGEN_INPUT_FILTER@" # The FILTER_PATTERNS tag can be used to specify filters on a per file pattern # basis. Doxygen will compare the file name with each pattern and apply the diff --git a/include/exec/ensure_started.hpp b/include/exec/ensure_started.hpp index 1c06cef0c..0dc840329 100644 --- a/include/exec/ensure_started.hpp +++ b/include/exec/ensure_started.hpp @@ -28,7 +28,6 @@ namespace experimental::execution { ///////////////////////////////////////////////////////////////////////////// - // [execution.senders.adaptors.ensure_started] namespace __ensure_started { using namespace __shared; diff --git a/include/exec/execute.hpp b/include/exec/execute.hpp index b728bcab2..135107c76 100644 --- a/include/exec/execute.hpp +++ b/include/exec/execute.hpp @@ -28,7 +28,6 @@ namespace experimental::execution { ///////////////////////////////////////////////////////////////////////////// - // [execution.execute] struct __execute_t { template diff --git a/include/exec/on.hpp b/include/exec/on.hpp index dfdec61ac..f79ea128a 100644 --- a/include/exec/on.hpp +++ b/include/exec/on.hpp @@ -20,7 +20,7 @@ namespace experimental::execution { ///////////////////////////////////////////////////////////////////////////// - // A scoped version of [execution.senders.adaptors.on] + // A scoped version of [exec.on] using on_t [[deprecated( "on_t has been moved to the " STDEXEC_PP_STRINGIZE(STDEXEC) ":: namespace")]] = STDEXEC::on_t; diff --git a/include/exec/sequence_senders.hpp b/include/exec/sequence_senders.hpp index 2a8847aa5..8cd61ca1d 100644 --- a/include/exec/sequence_senders.hpp +++ b/include/exec/sequence_senders.hpp @@ -261,7 +261,6 @@ namespace experimental::execution STDEXEC::_WITH_ENVIRONMENT_(_Env)...>; ///////////////////////////////////////////////////////////////////////////// - // [execution.seqtraits] namespace __sequence_sndr { struct get_item_types_t; diff --git a/include/exec/split.hpp b/include/exec/split.hpp index a345b1376..03c82f099 100644 --- a/include/exec/split.hpp +++ b/include/exec/split.hpp @@ -28,7 +28,6 @@ namespace experimental::execution { //////////////////////////////////////////////////////////////////////////// - // [execution.senders.adaptors.split] struct split_t { template , STDEXEC::sender_in<_Env> _CvSender> diff --git a/include/exec/start_detached.hpp b/include/exec/start_detached.hpp index 1aabab520..e9d2e26d6 100644 --- a/include/exec/start_detached.hpp +++ b/include/exec/start_detached.hpp @@ -29,7 +29,6 @@ namespace experimental::execution { ///////////////////////////////////////////////////////////////////////////// - // [execution.senders.consumer.start_detached] namespace __start_detached { struct __submit_receiver diff --git a/include/stdexec/__detail/__bulk.hpp b/include/stdexec/__detail/__bulk.hpp index 22136f102..0da2eeb30 100644 --- a/include/stdexec/__detail/__bulk.hpp +++ b/include/stdexec/__detail/__bulk.hpp @@ -34,7 +34,7 @@ STDEXEC_PRAGMA_IGNORE_GNU("-Wmissing-braces") namespace STDEXEC { ///////////////////////////////////////////////////////////////////////////// - // [execution.senders.adaptors.bulk] + // [exec.bulk] namespace __bulk { //! Wrapper for a policy object. diff --git a/include/stdexec/__detail/__connect.hpp b/include/stdexec/__detail/__connect.hpp index 8fe3a2eb4..9fcde6b5d 100644 --- a/include/stdexec/__detail/__connect.hpp +++ b/include/stdexec/__detail/__connect.hpp @@ -29,7 +29,7 @@ namespace STDEXEC { ///////////////////////////////////////////////////////////////////////////// - // [execution.senders.connect] + // [exec.connect] namespace __connect { template diff --git a/include/stdexec/__detail/__continues_on.hpp b/include/stdexec/__detail/__continues_on.hpp index 238891faa..690004f36 100644 --- a/include/stdexec/__detail/__continues_on.hpp +++ b/include/stdexec/__detail/__continues_on.hpp @@ -37,7 +37,7 @@ namespace STDEXEC { ///////////////////////////////////////////////////////////////////////////// - // [execution.senders.adaptors.continues_on] + // [exec.continues.on] namespace __trnsfr { template diff --git a/include/stdexec/__detail/__into_variant.hpp b/include/stdexec/__detail/__into_variant.hpp index 2125e768d..1dec4cacf 100644 --- a/include/stdexec/__detail/__into_variant.hpp +++ b/include/stdexec/__detail/__into_variant.hpp @@ -35,7 +35,7 @@ namespace STDEXEC { ///////////////////////////////////////////////////////////////////////////// - // [execution.senders.adaptors.into_variant] + // [exec.into.variant] namespace __into_variant { template diff --git a/include/stdexec/__detail/__just.hpp b/include/stdexec/__detail/__just.hpp index 455b76f5f..ff9df2215 100644 --- a/include/stdexec/__detail/__just.hpp +++ b/include/stdexec/__detail/__just.hpp @@ -32,7 +32,7 @@ STDEXEC_PRAGMA_IGNORE_GNU("-Wmissing-braces") namespace STDEXEC { ///////////////////////////////////////////////////////////////////////////// - // [execution.senders.factories] + // [exec.factories] namespace __just { template diff --git a/include/stdexec/__detail/__on.hpp b/include/stdexec/__detail/__on.hpp index 8b6768747..164844e2f 100644 --- a/include/stdexec/__detail/__on.hpp +++ b/include/stdexec/__detail/__on.hpp @@ -39,7 +39,7 @@ STDEXEC_PRAGMA_IGNORE_GNU("-Wmissing-braces") namespace STDEXEC { ///////////////////////////////////////////////////////////////////////////// - // [execution.senders.adaptors.on] + // [exec.on] struct _CANNOT_RESTORE_EXECUTION_CONTEXT_AFTER_ON_; namespace __on diff --git a/include/stdexec/__detail/__operation_states.hpp b/include/stdexec/__detail/__operation_states.hpp index 804e3fea4..ebe6798e1 100644 --- a/include/stdexec/__detail/__operation_states.hpp +++ b/include/stdexec/__detail/__operation_states.hpp @@ -50,7 +50,7 @@ namespace STDEXEC {}; ///////////////////////////////////////////////////////////////////////////// - // [execution.op_state] + // [exec.opstate] template concept __has_start_member = requires(_Op &__op) { __op.start(); }; @@ -153,7 +153,7 @@ namespace STDEXEC inline constexpr start_t start{}; ///////////////////////////////////////////////////////////////////////////// - // [execution.op_state] + // [exec.opstate] //! @brief An in-progress, *immovable*, *startable* representation of an //! asynchronous operation — the result of connecting a sender to diff --git a/include/stdexec/__detail/__queries.hpp b/include/stdexec/__detail/__queries.hpp index 737421724..7a0b3117c 100644 --- a/include/stdexec/__detail/__queries.hpp +++ b/include/stdexec/__detail/__queries.hpp @@ -30,7 +30,7 @@ namespace STDEXEC ////////////////////////////////////////////////////////////////////////////////////////////////// // [exec.queries] - // [exec.get.await.adapt], see https://eel.is/c++draft/exec#get.await.adapt + // [exec.get.await.adapt] struct get_await_completion_adaptor_t : __query { template diff --git a/include/stdexec/__detail/__receivers.hpp b/include/stdexec/__detail/__receivers.hpp index 75cc603a8..32069f5d9 100644 --- a/include/stdexec/__detail/__receivers.hpp +++ b/include/stdexec/__detail/__receivers.hpp @@ -46,7 +46,7 @@ namespace STDEXEC } // namespace __detail ///////////////////////////////////////////////////////////////////////////// - // [execution.receivers] + // [exec.recv] template concept __set_value_member = requires(_Receiver &&__rcvr, _As &&...__args) { static_cast<_Receiver &&>(__rcvr).set_value(static_cast<_As &&>(__args)...); diff --git a/include/stdexec/__detail/__schedule_from.hpp b/include/stdexec/__detail/__schedule_from.hpp index 209dc5090..242425946 100644 --- a/include/stdexec/__detail/__schedule_from.hpp +++ b/include/stdexec/__detail/__schedule_from.hpp @@ -28,7 +28,7 @@ namespace STDEXEC { ///////////////////////////////////////////////////////////////////////////// - // [execution.senders.adaptors.schedule_from] + // [exec.schedule.from] struct schedule_from_t { template diff --git a/include/stdexec/__detail/__sender_concepts.hpp b/include/stdexec/__detail/__sender_concepts.hpp index 62f28bd6b..ba38c776d 100644 --- a/include/stdexec/__detail/__sender_concepts.hpp +++ b/include/stdexec/__detail/__sender_concepts.hpp @@ -32,7 +32,7 @@ namespace STDEXEC { ///////////////////////////////////////////////////////////////////////////// - // [execution.senders] + // [exec.snd] //! @brief Tag type used to opt a class into the @c stdexec::sender concept. //! @@ -102,17 +102,17 @@ namespace STDEXEC //! @c sender_concept type alias derived from @c stdexec::sender_tag, //! or by specializing `stdexec::enable_sender` to @c true, or by //! being an awaitable in stdexec's coroutine promise type. - //! 2. @c S provides an environment via @c stdexec::get_env (every sender - //! has an environment, possibly empty). + //! 2. @c S provides a queryable set of attributes via @c stdexec::get_env. + //! Every sender has a (possibly empty) set of attributes. //! 3. @c S's decayed type is move-constructible and constructible from //! an @c S (this is what allows senders to be stored and forwarded //! by value). //! //! Note that @c sender by itself does *not* require the sender's //! completion signatures to be computable. That is the additional - //! constraint of @c sender_in (which carries an environment). Generic - //! sender-adaptor code that needs to know "what does this sender - //! complete with?" uses `sender_in`, not @c sender (alone). + //! constraint of @c sender_in. Generic sender-adaptor code that needs to + //! know "in which ways can this sender complete?" uses `sender_in`, + //! not @c sender (alone). //! //! See [exec.snd.concepts] in the C++26 working draft. //! @@ -140,10 +140,10 @@ namespace STDEXEC //! given environment. //! //! @c sender_in is the form of the sender concept that generic adaptor - //! code actually uses. Where @c sender just asks "is this a sender at - //! all?", `sender_in` asks "is @c S a sender whose completion - //! signatures we can compute when connected to a receiver with - //! environment @c Env?" — that information is what every adaptor needs + //! code actually uses. Where @c sender just asks \"is this a sender at + //! all?\", `sender_in` asks \"is @c S a sender whose completion + //! signatures can be computed when connected to a receiver with + //! environment @c Env?\" — that information is what every adaptor needs //! to type-check itself. //! //! Concretely, `sender_in` requires: @@ -155,8 +155,11 @@ namespace STDEXEC //! //! The @c Env parameter is optional (the variadic accepts zero or one //! environment). When no environment is supplied, the sender must have - //! a *dependent-environment-free* set of completion signatures — i.e. - //! its signatures must not vary by environment. + //! a *non-dependent* set of completion signatures — i.e. its signatures + //! are the same regardless of the environment. In that case, + //! @c sender_in requires that `get_completion_signatures()` is a + //! constant expression whose value is a valid @c completion_signatures + //! specialization. //! //! See [exec.snd.concepts] in the C++26 working draft. //! diff --git a/include/stdexec/__detail/__stopped_as_error.hpp b/include/stdexec/__detail/__stopped_as_error.hpp index 80212ace9..337f80035 100644 --- a/include/stdexec/__detail/__stopped_as_error.hpp +++ b/include/stdexec/__detail/__stopped_as_error.hpp @@ -29,7 +29,7 @@ namespace STDEXEC { ///////////////////////////////////////////////////////////////////////////// - // [execution.senders.adaptors.stopped_as_error] + // [exec.stopped.err] //! @brief A pipeable sender adaptor that converts a predecessor's stopped //! completion into an error completion carrying a user-supplied diff --git a/include/stdexec/__detail/__stopped_as_optional.hpp b/include/stdexec/__detail/__stopped_as_optional.hpp index 68ce46ec7..05d9092b3 100644 --- a/include/stdexec/__detail/__stopped_as_optional.hpp +++ b/include/stdexec/__detail/__stopped_as_optional.hpp @@ -37,7 +37,7 @@ namespace STDEXEC { ///////////////////////////////////////////////////////////////////////////// - // [execution.senders.adaptors.stopped_as_optional] + // [exec.stopped.opt] namespace __sao { struct _SENDER_MUST_HAVE_EXACTLY_ONE_VALUE_COMPLETION_WITH_ONE_ARGUMENT_; diff --git a/include/stdexec/__detail/__sync_wait.hpp b/include/stdexec/__detail/__sync_wait.hpp index 063902d16..083e8c774 100644 --- a/include/stdexec/__detail/__sync_wait.hpp +++ b/include/stdexec/__detail/__sync_wait.hpp @@ -44,8 +44,8 @@ STDEXEC_PRAGMA_IGNORE_MSVC(4714) // marked as __forceinline not inlined namespace STDEXEC::__sync_wait { ///////////////////////////////////////////////////////////////////////////// - // [execution.senders.consumers.sync_wait] - // [execution.senders.consumers.sync_wait_with_variant] + // [exec.sync.wait] + // [exec.sync.wait.var] struct __env { template <__one_of _Query> @@ -192,7 +192,7 @@ namespace STDEXEC::__sync_wait STDEXEC_P2300_NAMESPACE_BEGIN(this_thread) //////////////////////////////////////////////////////////////////////////// - // [execution.senders.consumers.sync_wait] + // [exec.sync.wait] //! @brief A sender consumer that synchronously blocks the calling thread //! until a sender completes and returns its result. diff --git a/include/stdexec/__detail/__then.hpp b/include/stdexec/__detail/__then.hpp index 882dbfa0b..e201ec66c 100644 --- a/include/stdexec/__detail/__then.hpp +++ b/include/stdexec/__detail/__then.hpp @@ -31,7 +31,7 @@ namespace STDEXEC { ///////////////////////////////////////////////////////////////////////////// - // [execution.senders.adaptors.then] + // [exec.then] namespace __then { struct __then_impl : __sexpr_defaults diff --git a/include/stdexec/__detail/__transfer_just.hpp b/include/stdexec/__detail/__transfer_just.hpp index 87881d035..d8165cb63 100644 --- a/include/stdexec/__detail/__transfer_just.hpp +++ b/include/stdexec/__detail/__transfer_just.hpp @@ -35,7 +35,6 @@ STDEXEC_PRAGMA_IGNORE_GNU("-Wmissing-braces") namespace STDEXEC { ///////////////////////////////////////////////////////////////////////////// - // [execution.senders.transfer_just] struct __transfer_just_t { template diff --git a/include/stdexec/__detail/__transform_sender.hpp b/include/stdexec/__detail/__transform_sender.hpp index fb4e07316..55157b1e9 100644 --- a/include/stdexec/__detail/__transform_sender.hpp +++ b/include/stdexec/__detail/__transform_sender.hpp @@ -30,7 +30,7 @@ STDEXEC_PRAGMA_IGNORE_EDG(type_qualifiers_ignored_on_reference) namespace STDEXEC { ///////////////////////////////////////////////////////////////////////////// - // [execution.transform_sender] + // [exec.snd.transform] namespace __detail { template @@ -167,7 +167,7 @@ namespace STDEXEC || __detail::__has_apply_sender; ///////////////////////////////////////////////////////////////////////////// - // [execution.apply_sender] + // [exec.snd.apply] inline constexpr struct apply_sender_t { template diff --git a/include/stdexec/__detail/__upon_error.hpp b/include/stdexec/__detail/__upon_error.hpp index e511b5d47..6294f719a 100644 --- a/include/stdexec/__detail/__upon_error.hpp +++ b/include/stdexec/__detail/__upon_error.hpp @@ -31,7 +31,7 @@ namespace STDEXEC { ///////////////////////////////////////////////////////////////////////////// - // [execution.senders.adaptors.upon_error] + // [exec.then] namespace __upon_error { struct __upon_error_impl : __sexpr_defaults diff --git a/include/stdexec/__detail/__upon_stopped.hpp b/include/stdexec/__detail/__upon_stopped.hpp index 82a07c0d1..34258a1aa 100644 --- a/include/stdexec/__detail/__upon_stopped.hpp +++ b/include/stdexec/__detail/__upon_stopped.hpp @@ -29,7 +29,7 @@ namespace STDEXEC { ///////////////////////////////////////////////////////////////////////////// - // [execution.senders.adaptors.upon_stopped] + // [exec.then] namespace __upon_stopped { struct __upon_stopped_impl : __sexpr_defaults diff --git a/include/stdexec/__detail/__when_all.hpp b/include/stdexec/__detail/__when_all.hpp index 827aace51..ea6844419 100644 --- a/include/stdexec/__detail/__when_all.hpp +++ b/include/stdexec/__detail/__when_all.hpp @@ -45,8 +45,7 @@ namespace STDEXEC { ///////////////////////////////////////////////////////////////////////////// - // [execution.senders.adaptors.when_all] - // [execution.senders.adaptors.when_all_with_variant] + // [exec.when.all] //! @brief A variadic sender factory that runs multiple senders concurrently //! and completes when all of them have completed, concatenating //! their value datums.