common_iterator::operator-> never says exactly what its return type is

[ericniebler]

Its return type is listed as "see below", and its Effects: clause describes the return values, but we should be more explicit about what the actual return type is in all cases.

(Editorially, I'll note this operator isn't given its own subsection or stable name.) Fixed in a0bd2cc.

Proposed Resolution

After [common.iter.op.star]/2 add a subsection title "common_iterator::operator->" with stable name [common.iter.op.ref]. Then change the following specification of common_iterator::operator-> as follows.

-see below operator->() const requires Readable<I>();
+decltype(auto) operator->() const requires Readable<I>();

 1 Requires: !is_sentinel

-2 Effects: Given an object i of type I
+2 Effects: Equivalent to:

-(2.1) — if I is a pointer type or if the expression i.operator->() is well-formed,
-        this function returns iter.
+(2.1) — return iter; if I is a pointer type or if the expression iter.operator->() is
+        well-formed.

-(2.2) — Otherwise, if the expression *iter is a glvalue, this function is equivalent
-        to return addressof(*iter);
+(2.2) — Otherwise, if the expression *iter is a glvalue:

+       auto&& tmp = *iter;
+       return addressof(tmp);

-(2.3) — Otherwise, this function returns a proxy object of an unspecified type
-        equivalent to the following:
+(2.3) — Otherwise, return proxy(*iter); where proxy is the exposition-only class:

     class proxy {
      value_type_t<I> keep_;
      proxy(reference_t<I>&& x)
        : keep_(std::move(x)) {}
     public:
       const value_type_t<I>* operator->() const {
          return addressof(keep_);
       }
    };

[ericniebler]

@CaseyCarter For your review.

[CaseyCarter]

After [common.iter.op.star]/2 add a subsection title "common_iterator::operator->" with stable name [common.iter.op.ref].

There is already such a section (after a0bd2cc); this PR need not add it. +1 otherwise.

[ericniebler]

I don't think the committee will have that document in front of them when they are reviewing this wording.

[CaseyCarter]

Fair enough; I'm reasonably certain the project editor won't be confused anyway.

[CaseyCarter]

LWG: don't forget to update the synopsis to agree.