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

Use of 'il' parameter name in functions taking initializer_lists inconsistent #5508

Closed
mattreecebentley opened this issue Jun 6, 2022 · 10 comments

Comments

@mattreecebentley
Copy link
Contributor

In general the use of 'il' in the definitions of functions in container overviews taking initializer_list's, appears to be of the form that 'il' is not specified, unless the function is described in subsequent sections.

I'm unclear why this is, as it is inconsistent with all other function parameters in the overview, with the exception of Allocator parameters.
At any rate, this is done inconsistently.

Eg. in deque.overview,
deque(initializer_list, const Allocator& = Allocator()); (consistent, not described in subsequent sections)

In forward_list.overview:
iterator insert_after(const_iterator position, initializer_list il); (consistent, described in subsequent sections)

In list.overview:
iterator insert(const_iterator position, initializer_list il); (inconsistent, doesn't have same definition in subsequent section)

In vector.overview:
constexpr iterator insert(const_iterator position, initializer_list il); (inconsistent, doesn't have same definition in subsequent section)

In vector.bool:
constexpr iterator insert(const_iterator position, initializer_list il); (inconsistent, not described in subsequent sections)

In multimap.overview
multimap(initializer_list<value_type> il, const Allocator& a)
: multimap(il, Compare(), a) { } (inconsistent, not described in subsequent sections)

(ditto set and unordered_map)

There are tons of other examples through the other sections of the standard.

@jensmaurer
Copy link
Member

First of all, we don't specify the definition of a function in the subsequent detailed section if it's already fully covered by the container requirements. Do you have an example where a function is not described, yet it's not covered by the container requirements?

The other concern I'm reading here is that we show a parameter name "il" in the synopsis of a container, yet there is no detailed specification (because the function is covered by the container requirements). That seems an editorial inconsistency, and a patch to remove the "il" from the declaration in the synopsis for those cases would be welcome.

@mattreecebentley
Copy link
Contributor Author

mattreecebentley commented Jun 8, 2022 via email

@jensmaurer
Copy link
Member

We might be missing some overall policy here. I think we agree that parameter names should be consistent between the synopsis and the detailed specification (if present).

For other functions: For parameters with a unique type (e.g. initializer_list), it seems a parameter name does not add comprehension value. (That's different if two or more parameters have the same type, e.g. when a pair of iterators is used; calling one "first" and the other "last" is helpful.)

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

mattreecebentley commented Oct 11, 2022 via email

@jwakely
Copy link
Member

jwakely commented Oct 11, 2022

I don't see a need for such a blanket rule. Is there actually a problem to be solved?

The parameter names only have meaning in the detailed description where we refer to those names, otherwise they are purely informative. "position" and "first" and "last" inform you of the intended meaning of an iterator parameter, "il" does not tell you anything useful. If we need to refer to il in the detailed description, it needs a name in the detail description. Otherwise, it doesn't. Either way, an initializer_list parameter doesn't need a name in a non-defining declaration in the synopsis, and I see no harm in omitting it there. Is there a reason they need to be consistent?

@mattreecebentley
Copy link
Contributor Author

I would argue that it's just less comprehensible to those who're not familiar with the very specific ruleset belonging to the inclusion/exclusion you are describing. Just writing new standardese is made more complicated by having to understand an additional rule here. The fact that we're even having a discussion about it is an indicator of that.
I prefer simplicity. Maybe we don't need a blanket rule across all parameters (however useful that might be to comprehension, it would be an onerous task), but I think parameter names should be consistent between the synopsis and the detailed specification. Otherwise it triggers a 'wait, but why...' in every newcomer.

@jwakely
Copy link
Member

jwakely commented Oct 13, 2022

But it doesn't matter for new standardese. If you want to name so your parameters, do that. If you want to omit parameter names where they aren't used or referred to by any detailed descriptions for a function, do that. LWG are not going to reject proposals on that basis. It doesn't matter, and so I don't see why we should decide on a rule and then change existing text. Making a rule that then has to be followed is more work and something extra to know.

@jwakely
Copy link
Member

jwakely commented Oct 13, 2022

Consistency between synopsis and detailed descriptions makes sense, but I'm not convinced anything beyond that solves a real problem.

@mattreecebentley
Copy link
Contributor Author

mattreecebentley commented Oct 13, 2022

But it doesn't matter for new standardese. If you want to name so your parameters, do that. If you want to omit parameter names where they aren't used or referred to by any detailed descriptions for a function, do that. LWG are not going to reject proposals on that basis. It doesn't matter, and so I don't see why we should decide on a rule and then change existing text. Making a rule that then has to be followed is more work and something extra to know.

When I said it makes a difference for new standardese, I'm referring to having things consistent between synopsis & descriptions. When someone like me is trying to adhere to the standard norms, sees that these are consistent, it provides a firm basis for writing. If they're not consistent, it's just confusing.
It sounds like we can wrap this up by saying there should be a patch to make the current inconsistencies between synopsis & descriptions consistent, and leave it at that.

@tkoeppe
Copy link
Contributor

tkoeppe commented Nov 8, 2022

Editorial meeting consensus: No change is needed here: Having unnamed parameters is widely done and is fine. We aren't consistent about whether an otherwise unused parameter should be named, but that's not in scope now. And as long as we don't use multiple different names for a parameter, there's nothing overly confusing here that needs addressing.

@tkoeppe tkoeppe closed this as not planned Won't fix, can't repro, duplicate, stale Nov 8, 2022
@tkoeppe tkoeppe removed the decision-required A decision of the editorial group (or the Project Editor) is required. label Nov 8, 2022
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

4 participants