Closed
Description
In the library, we have a term of art "equivalent to" to specify effects. What we don't have is a consistent way of formatting it. Currently observed forms:
- Equivalent to: [codeblock]
- Equivalent to:
statement;
- Equivalent to:
expression;
- Equivalent to
expression
. - Equivalent to
statement;
where foo is bar.
I think we should definitely have the colon after "to", and we should probably have both a codeblock and an inline form.
Metadata
Metadata
Assignees
Labels
No labels
Type
Projects
Milestone
Relationships
Development
No branches or pull requests
Activity
jwakely commentedon Nov 24, 2016
This was discussed earlier this year. I think we agreed that the third form is wrong (we shouldn't use a semi-colon after an expression, only after a statement) but that we do want all three of codeblock/statement/expression.
jensmaurer commentedon Nov 24, 2016
It seems we're using "Equivalent to
expression
." quite a lot, and only use a colon if a statement or codeblock follows.tkoeppe commentedon Nov 24, 2016
Maybe we can settle on these forms:
Codeblock
-?- Effects: Equivalent to:
where we may optionally explain things used in the block.
Inline statement
-?- Effects: Equivalent to:
statement;
Inline expression
-?- Effects: Equivalent to
expression
.-?- Effects: Equivalent to
f(n)
, wheren
is a value.jensmaurer commentedon Nov 24, 2016
Sounds minimally-invasive vs. the status quo.
jwakely commentedon Nov 24, 2016
I think that's what we agreed to use previously, yes.
See also #694
jensmaurer commentedon Nov 24, 2016
@tkoeppe: Given Richard's explanation in #694, is there still some open issue? Note that the third of your forms above is a statement-expression, i.e. a valid statement.
tkoeppe commentedon Nov 24, 2016
OK, I think the detail that was missing from #694 is how to deal with continuing sentences, e.g. when something needs a retrospective definition. My concrete proposal here is to place a comma after an inline statement and never use an inline expression.
jensmaurer commentedon Nov 24, 2016
Do you have specific examples?
tkoeppe commentedon Nov 24, 2016
@jensmaurer: I realise that's a valid statement, but the idea is to partially specialize on such patterns and prefer "inline
expression
." when possible.tkoeppe commentedon Nov 24, 2016
@jensmaurer: E.g. 20.7.2.4/1. I would add a comma there. 20.7.4/10 is particularly weird. Also 20.14.9/1.
tkoeppe commentedon Nov 24, 2016
Some "equivalent to" statements are also just poorly constructed. E.g. 21.3.1.6.2, compare p6 vs p17. I think the latter ("Equivalent to
f()
.") should be preferred over the former ("Equivalent to:return f();
"). We should add an appropriate rule.tkoeppe commentedon Nov 24, 2016
@jensmaurer: Please leave this bug open until we have at least updated the style wiki.
jensmaurer commentedon Nov 24, 2016
"Equivalent to:
return expression;
" vs. "Equivalent toexpression
." We usually do "returnexpression
" if expression has a type other than void, but it seems to me the simplerexpression
might be better. (47 obvious occurrences of the former.)zygoloid commentedon Nov 24, 2016
If I recall correctly, we chose to use "Equivalent to:
return expression;
" in cases where a return value is produced, to make the connection between the expression and the value clearer.See https://github.com/cplusplus/draft/wiki/Specification-Style-Guidelines#writing-effects-in-a-function-description for the existing description of the rules here.
jensmaurer commentedon Nov 25, 2016
@tkoeppe: That covers it, right?
7 remaining items