Closed
Description
It's unclear when an Effects: clause is specifying an expression verses a code block. As a result, the trailing ; on intended code blocks ends up looking like a typo. (I've inadvertently 'fixed' a few of these apparent 'typos' myself).
To tell when the Effects is specifying a code block with statement(s) vs. an expression, I propose we follow the convention used in [thread.condition.condvar] (and elsewhere) which uses a : before code blocks. Examples:
Effects: Equivalent to expr.
Effects: Equivalent to: code;
OK?
-- in related e-mail correspondence --
from Richard:
- The convention we've been following is that the "Equivalent to" is followed by either an expression (in which case there is a non-code-font period after the expression) or a statement (in which case it is a complete statement, typically terminated by a semicolon, and there is no following period). I've been using inline code when it fits and using a code block otherwise (and in the latter case, an expression loses its trailing period).
from STL:
- As a library developer, my expectation for "Effects: Equivalent to MEOW" is that I can copy-paste MEOW and (modulo the usual stuff, like _Ugly names, ADL defenses, As If Rule, etc.) it is a conforming implementation. If the function has a non-void return type, I expect the return statement to be part of MEOW.
Metadata
Metadata
Assignees
Labels
No labels
Type
Projects
Milestone
Relationships
Development
No branches or pull requests
Activity
zygoloid commentedon Apr 14, 2016
Let's have three different forms:
No colon, period following expression.
Colon, no period, full statement including semicolon.
Colon, no period, full statement including semicolon(s), in code block.
If an expression doesn't fit in the first form, we should convert it to a statement and use the third form.
burblebee commentedon Apr 14, 2016
That's the plan, but if the text is already:
Effects: Equivalent to statement;
I plan to use the 2nd form because of the feedback from STL quoted above.
There is also a problem where we have:
Effects: statement;
with no verb to introduce the code. I'll probably leave these alone until after LWG has had a chance to review these and determine if they were supposed to be:
Effects: Equivalent to: statement;
If not, I would like to find some introduction other than "Equivalent to". Maybe:
Effects: As if by: statement;
?jwakely commentedon Apr 14, 2016
Whatever style gets decided on, please make sure it's documented at https://github.com/cplusplus/draft/wiki/Specification-Style-Guidelines and inform LWG, otherwise nobody will follow the convention.
Fix \effects throughout the library (#694 part 1)
Use "As if by" in \effects which lack a code introduction (#694 part 2)
Fix \effects throughout the library (cplusplus#694 part 1)
Use "As if by" in \effects which lack a code introduction (cplusplus#694