Description inconsistencies around buffer constructors and buffer::set_final_data()

[AlexeySachkov]

buffer::set_final_data is defined as follows (emphasis mine):

template <typename Destination = std::nullptr_t> void set_final_data(Destination finalData = nullptr)

The finalData points to where the outcome of all the buffer processing is going to be copied to at destruction time, if the buffer was involved with a write accessor.

Destination can be either an output iterator or a std::weak_ptr<T>.

Note that a raw pointer is a special case of output iterator and thus defines the host memory to which the result is to be copied.

In the case of a weak pointer, the output is not updated if the weak pointer has expired.

If Destination is std::nullptr_t, then the copy back will not happen.

It is referenced from a number of constructors, but differently every time (emphasis mine):

Data is not written back to the host on destruction of the buffer unless the buffer has a valid non-null pointer specified via the member function set_final_data().

Since the hostData is const, this buffer is only initialized with this memory and there is no write back after its destruction, unless the buffer has another valid non-null final data address specified via the member function set_final_data() after construction of the buffer.

However, if the buffer has a valid non-const iterator specified via the member function set_final_data(), data will be copied back to that iterator.

I think it would be better if set_final_data() was referenced uniformly from all constructors. It also doesn't make sense to account for const iterators, because they are not output iterators and therefore can't be passed to set_final_data() at all.

[psalz]

Somewhat related CTS issue: KhronosGroup/SYCL-CTS#877

[keryell]

It also doesn't make sense to account for const iterators, because they are not output iterators and therefore can't be passed to set_final_data() at all.

The idea was to emphasize the fact that even if you have a buffer made from a const iterator, you can still write back, by using a non-const iterator, by opposition.