[meta, thread] Add/amend references to func.require, func.invoke #5859
Conversation
source/threads.tex
Outdated
| @@ -1669,7 +1669,7 @@ | |||
| Initializes \tcode{ssource}. | |||
| The new thread of execution executes | |||
| \begin{codeblock} | |||
| invoke(auto(std::forward<F>(f)), get_stop_token(), | |||
| invoke(auto(std::forward<F>(f)), get_stop_token(), // see \ref{func.invoke}, \ref{thread.jthread.stop} | |||
There was a problem hiding this comment.
We should not add a cross-reference for get_stop_token; it's right in this (or the next) section.
There was a problem hiding this comment.
Agreed.
It's a bit annoying that the comment is not a great place for the cross-reference, since it's not clear which bit of the code it refers to (forward? auto? invoke?). I wonder if an explicit note (e.g. "invoke is defined in \ref(...)") would be clearer -- thoughts?
There was a problem hiding this comment.
trying "for invoke, see \ref{...}", does that look OK?
|
Personal experience: I often look up INVOKE based on conversations outside the standard. I always start with the main index, thinking it is not an identifier in the library, and fall back on the index of library names as my second choice. Hence, I advocate adding/moving to the main index. Note that this should have no bearing on whether we add internal cross-references as well! |
|
Even if we do add cross-references, I don't think we need to add them repeatedly within the same subclause -- just the first time it comes up? E.g. we do this in [basic.extended.fp], where we say "extended floating-point type" many times, but only the first mention gets a cross-reference. |
from [meta] and [threads] In particular, not knowing where to find the definition of *INVOKE* (it's in the library index, but not the main index) is highly frustrating when reading is_invocable et al. Corrected references in [threads] and added some more for completeness. There's a bunch of uses of 'invoke' in [algorithm] and [ranges] that could also have references added, but that feels less necessary.
Co-authored-by: Johel Ernesto Guerrero Peña <johelegp@gmail.com>
Co-authored-by: Johel Ernesto Guerrero Peña <johelegp@gmail.com>
ecatmur
requested review from
JohelEGP and
jensmaurer
and removed request for
JohelEGP
Co-authored-by: Johel Ernesto Guerrero Peña <johelegp@gmail.com>
|
I think this should be approved. |
In particular, not knowing where to find the definition of INVOKE (it's in the library index, but not the main index) is highly frustrating when reading is_invocable et al.
Corrected references in [thread] and added some more for completeness.
There's a bunch of uses of 'invoke' in [algorithm] and [ranges] that could also have references added, but that feels less necessary.