Merge pull request #2108 from ericniebler/stable-names-in-docs

ericniebler · web-flow · commit dfd5925c8ab4 · 2026-06-17T07:39:01.000-07:00
correct all C++ stable section names mentioned in the source
diff --git 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 <stddef.h>"
                 COMMAND c++ -xc -dI -E -
diff --git 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 <https://eel.is/c++draft> 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
@@ -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
@@ -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
@@ -28,7 +28,6 @@
 namespace experimental::execution
 {
   /////////////////////////////////////////////////////////////////////////////
-  // [execution.execute]
   struct __execute_t
   {
     template <STDEXEC::scheduler _Scheduler, STDEXEC::__std::move_constructible _Fun>
diff --git 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
@@ -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
@@ -28,7 +28,6 @@
 namespace experimental::execution
 {
   ////////////////////////////////////////////////////////////////////////////
-  // [execution.senders.adaptors.split]
   struct split_t
   {
     template <class _Env = STDEXEC::env<>, STDEXEC::sender_in<_Env> _CvSender>
diff --git 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
@@ -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
@@ -29,7 +29,7 @@
 namespace STDEXEC
 {
   /////////////////////////////////////////////////////////////////////////////
-  // [execution.senders.connect]
+  // [exec.connect]
   namespace __connect
   {
     template <class _Sender, class _Receiver>
diff --git 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 <class... _Values>
diff --git 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 <class _Sender, class _Env>
diff --git 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 <class _SetTag>
diff --git 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
@@ -50,7 +50,7 @@ namespace STDEXEC
   {};
 
   /////////////////////////////////////////////////////////////////////////////
-  // [execution.op_state]
+  // [exec.opstate]
   template <class _Op>
   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
@@ -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<get_await_completion_adaptor_t>
   {
     template <class _Env>
diff --git 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 <class _Receiver, class... _As>
   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
@@ -28,7 +28,7 @@
 namespace STDEXEC
 {
   /////////////////////////////////////////////////////////////////////////////
-  // [execution.senders.adaptors.schedule_from]
+  // [exec.schedule.from]
   struct schedule_from_t
   {
     template <sender _Sender>
diff --git 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<S>` 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<S, Env>`, 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<S, Env>`,
+  //! 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<S, Env>` 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<S, Env>` 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<S, Env>` 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<S>()` 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
@@ -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
@@ -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
@@ -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<get_scheduler_t, get_start_scheduler_t, get_delegation_scheduler_t> _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
@@ -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
@@ -35,7 +35,6 @@ STDEXEC_PRAGMA_IGNORE_GNU("-Wmissing-braces")
 namespace STDEXEC
 {
   /////////////////////////////////////////////////////////////////////////////
-  // [execution.senders.transfer_just]
   struct __transfer_just_t
   {
     template <scheduler _Scheduler, __movable_value... _Values>
diff --git 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 <class _Domain, class _OpTag>
@@ -167,7 +167,7 @@ namespace STDEXEC
     || __detail::__has_apply_sender<default_domain, _Tag, _Sender, _Args...>;
 
   /////////////////////////////////////////////////////////////////////////////
-  // [execution.apply_sender]
+  // [exec.snd.apply]
   inline constexpr struct apply_sender_t
   {
     template <class _Domain, class _Tag, class _Sender, class... _Args>
diff --git 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
@@ -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
@@ -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.

Original file line number	Diff line number	Diff line change
`@@ -28,7 +28,6 @@`
`28`	`28`	`namespace experimental::execution`
`29`	`29`	`{`
`30`	`30`	`/////////////////////////////////////////////////////////////////////////////`
`31`		`- // [execution.senders.adaptors.ensure_started]`
`32`	`31`	`namespace __ensure_started`
`33`	`32`	`{`
`34`	`33`	`using namespace __shared;`
Original file line number	Diff line number	Diff line change
`@@ -20,7 +20,7 @@`
`20`	`20`	`namespace experimental::execution`
`21`	`21`	`{`
`22`	`22`	`/////////////////////////////////////////////////////////////////////////////`
`23`		`- // A scoped version of [execution.senders.adaptors.on]`
	`23`	`+ // A scoped version of [exec.on]`
`24`	`24`	`using on_t [[deprecated(`
`25`	`25`	`"on_t has been moved to the " STDEXEC_PP_STRINGIZE(STDEXEC) ":: namespace")]] = STDEXEC::on_t;`
`26`	`26`
Original file line number	Diff line number	Diff line change
`@@ -261,7 +261,6 @@ namespace experimental::execution`
`261`	`261`	`STDEXEC::_WITH_ENVIRONMENT_(_Env)...>;`
`262`	`262`
`263`	`263`	`/////////////////////////////////////////////////////////////////////////////`
`264`		`- // [execution.seqtraits]`
`265`	`264`	`namespace __sequence_sndr`
`266`	`265`	`{`
`267`	`266`	`struct get_item_types_t;`
Original file line number	Diff line number	Diff line change
`@@ -29,7 +29,6 @@`
`29`	`29`	`namespace experimental::execution`
`30`	`30`	`{`
`31`	`31`	`/////////////////////////////////////////////////////////////////////////////`
`32`		`- // [execution.senders.consumer.start_detached]`
`33`	`32`	`namespace __start_detached`
`34`	`33`	`{`
`35`	`34`	`struct __submit_receiver`
Original file line number	Diff line number	Diff line change
`@@ -34,7 +34,7 @@ STDEXEC_PRAGMA_IGNORE_GNU("-Wmissing-braces")`
`34`	`34`	`namespace STDEXEC`
`35`	`35`	`{`
`36`	`36`	`/////////////////////////////////////////////////////////////////////////////`
`37`		`- // [execution.senders.adaptors.bulk]`
	`37`	`+ // [exec.bulk]`
`38`	`38`	`namespace __bulk`
`39`	`39`	`{`
`40`	`40`	`//! Wrapper for a policy object.`