Inconsistent parameter name "capacity"

[mgeier]

I've been told that parameter names are not part of the API, so this might not matter at all (except to pedantic people like me):

I've found 17 functions with the name with_capacity(): https://doc.rust-lang.org/stable/std/index.html?search=with_capacity

Most of them use capacity as parameter name:

1. https://doc.rust-lang.org/alloc/vec/struct.Vec.html#method.with_capacity
2. https://doc.rust-lang.org/std/vec/struct.Vec.html#method.with_capacity
3. https://doc.rust-lang.org/alloc/string/struct.String.html#method.with_capacity
4. https://doc.rust-lang.org/std/string/struct.String.html#method.with_capacity
5. https://doc.rust-lang.org/alloc/collections/binary_heap/struct.BinaryHeap.html#method.with_capacity
6. https://doc.rust-lang.org/std/collections/binary_heap/struct.BinaryHeap.html#method.with_capacity
7. https://doc.rust-lang.org/std/collections/struct.HashSet.html#method.with_capacity
8. https://doc.rust-lang.org/std/collections/struct.HashSet.html#method.with_capacity_and_hasher
9. https://doc.rust-lang.org/std/collections/struct.HashMap.html#method.with_capacity
10. https://doc.rust-lang.org/std/collections/struct.HashMap.html#method.with_capacity_and_hasher
11. https://doc.rust-lang.org/std/path/struct.PathBuf.html#method.with_capacity
12. https://doc.rust-lang.org/std/ffi/struct.OsString.html#method.with_capacity

Some functions, however, use cap as argument name:

1. https://doc.rust-lang.org/std/io/struct.LineWriter.html#method.with_capacity
2. https://doc.rust-lang.org/std/io/struct.BufWriter.html#method.with_capacity
3. https://doc.rust-lang.org/std/io/struct.BufReader.html#method.with_capacity

Others are using n:

1. https://doc.rust-lang.org/alloc/collections/vec_deque/struct.VecDeque.html#method.with_capacity
2. https://doc.rust-lang.org/std/collections/vec_deque/struct.VecDeque.html#method.with_capacity

Wouldn't it make sense to call all of them capacity?

Does anyone care about such things?

If yes, we could play the same game with swap() and probably with other common functions.

[estebank]

Parameter names are not part of the API because arguments in Rust are always only positional, which means that changing the name is never a breaking change. This means that we both don't care to change it nor to keep it as is ^_^

I think this is for T-libs/T-docs to decide.

[nagisa]

I encourage you to post a PR which unifies the names. They appear in the documentation, so this is essentially a documentation improvement, and those are generally well accepted.

[mgeier]

I encourage you to post a PR which unifies the names.

Done: #60316