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

[flat.map.defn] [flat.multimap.defn] Exposition-only markup for "c" and "compare" #5914

Closed
wants to merge 1 commit into from

Conversation

Quuxplusone
Copy link
Contributor

@Quuxplusone Quuxplusone commented Oct 25, 2022

flat_set already has the correct \exposid markup.

Fixes #5812.

@JohelEGP
Copy link
Contributor

See #5812.

@JohelEGP
Copy link
Contributor

JohelEGP commented Oct 25, 2022

This is repeating the same mistakes explained at #5696 (comment). This means that there are many more places left to mark with \exposid than those you've actually marked.

containers c; // \expos
key_compare compare; // \expos
containers \exposid{c}; // \expos
key_compare \exposid{compare}; // \expos

struct key_equiv { // \expos
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think key_equiv should also be formatted with \exposid{}. Perhaps its comp member should also be considered exposition only, although not strictly needed due to priority_queue's comp.

(How about changing to kebab-case and/or eliminating its ctor as aggregate initialization can do the right thing?)

@jensmaurer
Copy link
Member

I think we agree we have an inconsistency, but my preference would be to address all of [containers] and add \exposid and kebab-case throughout.

However, we should confirm with @tkoeppe and the rest of the editorial group whether we really want that, and then we should strive for a comprehensive patch.

@jensmaurer jensmaurer added the decision-required A decision of the editorial group (or the Project Editor) is required. label Oct 26, 2022
@Quuxplusone
Copy link
Contributor Author

I think we agree we have an inconsistency, but my preference would be to address all of [containers]

Before making this PR, I wasn't aware of the apparent controversy here. :) Perhaps there's more to do after this; but the question for me is simply, does anyone claim there's less to do? Right now the formatting is in a "very" inconsistent state, where if you scroll down through https://eel.is/c++draft/flat.map.defn you'll see : c(), compare(comp) with the names upright (like in https://eel.is/c++draft/priority.queue , although to be fair https://eel.is/c++draft/priority.queue doesn't use member-initializer-lists), and if you scroll down through https://eel.is/c++draft/flat.set.defn : c(), compare(comp) with the names italicized. This suggests there is a difference between how the name is used in flat_set versus how it's used in priority_queue and flat_map. But that suggestion is misleading.

I can certainly imagine that people want to italicize other expos-only members, like key_equiv and value_compare.comp and so on; I have no particular opinion on those personally because AFAICT the current state of the world there isn't currently inconsistent with anything. So IMHO the larger discussion needn't block this small consistency patch.

@@ -14895,8 +14895,8 @@
{ x.swap(y); }

private:
containers c; // \expos
key_compare compare; // \expos
containers \exposid{c}; // \expos
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There was one thing I wasn't sure how to do markup-wise, so I left it alone / out-of-scope: Line 14978 has

Initializes \tcode{c.keys} with \tcode{std::move(key_cont)}

where ideally the c should be expos-only but the keys shouldn't.

Copy link
Contributor

@JohelEGP JohelEGP Oct 26, 2022

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is what I meant with #5914 (comment). By convention, marking with \exposid in the class synopsis is not enough. All uses of those members throughout are marked with \exposid.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think you can just use

Initializes \tcode{\exposid{c}.keys} with \tcode{std::move(key_cont)}

@tkoeppe
Copy link
Contributor

tkoeppe commented Nov 8, 2022

Editorial meeting comment: we would like a consistent style across all four new "flat" container adaptors: exposition-only members should be marked up with \exposid, and their names are not required to end in underscores. (I believe that none of them currently do, so no change is needed.) We should only focus on those four class templates here, and leave considerations about the rest of the standard for the future.

@tkoeppe
Copy link
Contributor

tkoeppe commented Nov 8, 2022

For tangential context: the discussion on how to name exposition-only members is in #4702.

@Quuxplusone
Copy link
Contributor Author

Editorial meeting comment: we would like a consistent style across all four new "flat" container adaptors: exposition-only members should be marked up with \exposid, and their names are not required to end in underscores. (I believe that none of them currently do, so no change is needed.) We should only focus on those four class templates here, and leave considerations about the rest of the standard for the future.

FWIW, I'm happy to do the grunt work and update this PR if it's helpful, but I wasn't in that meeting and therefore don't really understand what was agreed upon. Would the non-obvious part be like this?

    containers \exposid{c};               // \expos
    key_compare \exposid{compare};        // \expos

    struct \exposid{key-equiv} {  // \expos
      \exposid{key-equiv}(key_compare c) : comp(c) { }
      bool operator()(const_reference x, const_reference y) const {
        return !comp(x.first, y.first) && !comp(y.first, x.first);
      }
      key_compare comp;
    };

AFAICT the name of key_compare comp (which matters only w.r.t macro.names/1), and the fact that it's captured by value (yikes), are not exposition-only, under the current wording. I also wish that exposition-only one-arg ctor were explicit.

@Quuxplusone
Copy link
Contributor Author

Abandoning.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
decision-required A decision of the editorial group (or the Project Editor) is required.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

Style exposition-only members of flat_map, flat_multimap, flat_set, flat_multiset consistently
5 participants