Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Formatting in "Effects: Equivalent to" is confusing #694

Closed
burblebee opened this issue Apr 13, 2016 · 3 comments
Closed

Formatting in "Effects: Equivalent to" is confusing #694

burblebee opened this issue Apr 13, 2016 · 3 comments
Assignees

Comments

@burblebee
Copy link
Contributor

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.
@burblebee burblebee self-assigned this Apr 13, 2016
@zygoloid
Copy link
Member

Let's have three different forms:

Effects: Equivalent to expr.

No colon, period following expression.

Effects: Equivalent to: statement;

Colon, no period, full statement including semicolon.

Effects: Equivalent to:

   statement1;
   statement2;

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
Copy link
Contributor Author

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
Copy link
Member

jwakely commented 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.

FrankHB pushed a commit to FrankHB/draft that referenced this issue Jul 9, 2016
Fixes include:
* insert ':' before codeblocks (cplusplus#694)
* fix punctuation and capitalization
* turn long \tcode'd code into codeblocks
* fix inconsistencies
* other minor edits in \effects clauses noticed while scanning thru source

Fixes cplusplus#694.
FrankHB pushed a commit to FrankHB/draft that referenced this issue Jul 9, 2016
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

3 participants