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.

It seems we're using "Equivalent to expression." quite a lot, and only use a colon if a statement or codeblock follows.

Maybe we can settle on these forms:

Codeblock

-?- Effects: Equivalent to:

statement;

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), where n is a value.

Sounds minimally-invasive vs. the status quo.

I think that's what we agreed to use previously, yes.

See also #694

@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.

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.

Do you have specific examples?

@jensmaurer: I realise that's a valid statement, but the idea is to partially specialize on such patterns and prefer "inline expression." when possible.

@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.

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.

@jensmaurer: Please leave this bug open until we have at least updated the style wiki.

"Equivalent to: return expression;" vs. "Equivalent to expression." We usually do "return expression" if expression has a type other than void, but it seems to me the simpler expression might be better. (47 obvious occurrences of the former.)

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.

@tkoeppe: That covers it, right?

@jensmaurer: The wiki is still missing information on how to continue with trailing definitions after the code, and maybe it should include a disambiguation rule for "equivalent to function-call" that I mentioned above.

I've updated the wiki.