Skip to content

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

Closed
@burblebee

Description

@burblebee

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.

Activity

self-assigned this
on Apr 13, 2016
zygoloid

zygoloid commented on Apr 14, 2016

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

burblebee commented on Apr 14, 2016

@burblebee
ContributorAuthor

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

jwakely commented on Apr 14, 2016

@jwakely
Member

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.

added a commit that references this issue on Apr 16, 2016
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

    Development

    No branches or pull requests

      Participants

      @zygoloid@jwakely@burblebee

      Issue actions

        Formatting in "Effects: Equivalent to" is confusing · Issue #694 · cplusplus/draft