Ambiguous explanation of capacity of type Vec in std doc page.

Location (URL)

https://doc.rust-lang.org/std/vec/struct.Vec.html

Summary

I have problem understanding Vec 's documentation.
The quotes from doc. All three provided in order in witch they are in text

Quote 1 ("Capacity and reallocation" section):

The capacity of a vector is the amount of space allocated for any future elements that will be added onto the vector.

Quote 2 ("Guarantees" section):

the reported capacity is completely accurate, and can be relied on. It can even be used to manually free the memory allocated by a Vec if desired.

Quote 3 ("Guarantees" section):

It is guaranteed, in order to respect the intentions of the programmer, that all of vec![e_1, e_2, ..., e_n], vec![x; n], and Vec::with_capacity(n) produce a Vec that requests an allocation of the exact size needed for precisely n elements from the allocator, and no other size (such as, for example: a size rounded up to the nearest power of 2). The allocator will return an allocation that is at least as large as requested, but it may be larger.

Quote 4 ("Guarantees" section):

It is guaranteed that the Vec::capacity method returns a value that is at least the requested capacity and not more than the allocated capacity.

Now i try to make sense of them all. First quote establishes that capacity is the amount of elements vector has an allocated space for. Second quote says that it is guaranteed that the capacity is always reported correctly, ok so if i execute this method i will get the number of elements the vector has allocated space for and even can use it to manually free the memory, so the capacity is the value that is used to keep track of allocation.

Third quote establishes that vector creation methods will ask allocator for exactly as many memory as they need but allocator can allocate more (as far as i understood it).

Fourth quote says that reported capacity can be anywhere between "requested capacity" (witch i assume it is the capacity requested when vector was created) and "allocated capacity".

The ones i have problems with are third and fourth quotes.

Third quote does not say what capacity does vector get if allocator returns more memory than needed.

Having capacity to be "requested capacity" makes it impossible to use it to manipulate memory correctly with it as "allocated capacity" is needed for that. And having capacity to be anything in between the two does not even make any sense.

Start at the std::vec::Vec documentation page, especially the “Capacity and reallocation” and “Guarantees” sections quoted in the issue. Trace how the documentation distinguishes requested, reported, and allocated capacity, then revise the explanation so their relationship and the allocator’s possible extra space are unambiguous. Done when the quoted guarantees no longer appear contradictory to a reader.