Skip to content

Style of "equivalent to" #1119

Closed
Closed
@tkoeppe

Description

@tkoeppe
Contributor

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:

  1. Equivalent to: [codeblock]
  2. Equivalent to: statement;
  3. Equivalent to: expression;
  4. Equivalent to expression.
  5. 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.

Activity

jwakely

jwakely commented on Nov 24, 2016

@jwakely
Member

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

jensmaurer commented on Nov 24, 2016

@jensmaurer
Member

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

tkoeppe

tkoeppe commented on Nov 24, 2016

@tkoeppe
ContributorAuthor

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.

jensmaurer

jensmaurer commented on Nov 24, 2016

@jensmaurer
Member

Sounds minimally-invasive vs. the status quo.

jwakely

jwakely commented on Nov 24, 2016

@jwakely
Member

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

See also #694

jensmaurer

jensmaurer commented on Nov 24, 2016

@jensmaurer
Member

@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

tkoeppe commented on Nov 24, 2016

@tkoeppe
ContributorAuthor

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

jensmaurer commented on Nov 24, 2016

@jensmaurer
Member

Do you have specific examples?

tkoeppe

tkoeppe commented on Nov 24, 2016

@tkoeppe
ContributorAuthor

@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

tkoeppe commented on Nov 24, 2016

@tkoeppe
ContributorAuthor

@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

tkoeppe commented on Nov 24, 2016

@tkoeppe
ContributorAuthor

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

tkoeppe commented on Nov 24, 2016

@tkoeppe
ContributorAuthor

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

jensmaurer

jensmaurer commented on Nov 24, 2016

@jensmaurer
Member

"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.)

zygoloid

zygoloid commented on Nov 24, 2016

@zygoloid
Member

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

jensmaurer commented on Nov 25, 2016

@jensmaurer
Member

@tkoeppe: That covers it, right?

7 remaining items

Loading
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@tkoeppe@jensmaurer

      Issue actions

        Style of "equivalent to" · Issue #1119 · cplusplus/draft