Docs only talks about “setting elements” which means an assignment operation if I understand things correctly.
(unless you mean that docs do not mention that by resizing the return value you unshare it - indeed it could be improved and this information could be added)
My understanding of this design decision is as follows:
xis informed (viaflags.how) thatyuses the same data asxowns, soxis not allowed to be resized, as it could corruptywhich reusesxs data.- However, reallocating
ydoes not affectx. If you allocate a new memory foryyou are sure that it will not corruptx.
(of course the design also could be that y would be disallowed to be reallocated, but I assume that the developer of this functionality did not want to introduce such a restriction as it was not needed)