`Allocator::grow` documentation

Location (URL)

https://doc.rust-lang.org/core/alloc/trait.Allocator.html#method.grow

Summary

The current documentation for Allocator::grow has parts which seem a little ambiguous, as discussed on Zulip here.

In particular, the current phrasing talks about memory ownership being "transferred to this allocator," which a user could misinterpret as referring to memory transfer between two allocators, instead of from the caller back to the original allocator.

Additionally, it seems like "memory/memory block" are used to refer to both an allocation with full temporal provenance (when talking about ownership transfer back to the allocator) and the memory contents without temporal provenance attached (when talking about how the old memory contents are accessible through the newly returned pointer, which comes with new temporal provenance).

Putting these together, I propose to change the documentation to look like this, with changes in bold. Here I replaced "returned" with "transferred" and wrote "memory block" instead of "allocation," to clarify the two points above. I also added another clarifying sentence, as per a suggestion in the Zulip conversation.

If this returns Ok, then ownership of the allocation referenced by ptr has been returned to this allocator. Any access to the old ptr is Undefined Behavior, even if the allocation was grown in-place. In particular, it is UB to offset the old ptr, except if the offset is 0, since it is now derived from a freed allocation. The newly returned pointer is the only valid pointer for accessing this memory now.

If this method returns Err, then ownership of the allocation has not been returned to this allocator, and the contents of the memory block are unaltered.

Start at the Allocator::grow documentation in the linked core::alloc::Allocator API entry. Compare the current ownership and memory-block wording with the proposed replacement and the linked Zulip discussion. Done means the documentation clearly distinguishes returning allocation ownership, invalidating the old pointer, and preserving contents when the method returns Err.