Broadcast channel capacity is not well-documented

[mdacach]

Description
tokio::sync::broadcast documentation states that the capacity parameter is an upper bound on the number of values the channel may retain at any given time.
But when creating the channel, this capacity is actually rounded up to the nearest power of two - thus the constraint that capacity <= usize::MAX / 2 on channel()

Solution
I guess we want to either

1. commit to rounding up to the next power of two and update the docs to state that, or
2. have the docs clarify that the actual channel capacity is >= than capacity, (but then the constraint of capacity <= usize::MAX / 2 is not clear)

For context, I came across this messing around with the example code:

[mdacach]

Follow-up question: why round up the capacity at all?

update: I now see that a bitmask is used. We probably want to commit to the power of two, then. I will open up a PR with suggested writing tomorrow.

[hawkw]

I think it would be preferable to change the docs to state that the channel's capacity will be at least capacity, rather than publicly committing to power of two capacities. The bitmask is an internal implementation detail, and if it's possible to document the behavior clearly in a way that does not commit to maintaining that internal implementation detail forever, that's probably better.

[hawkw]

For comparison, the documentation for Vec::with_capacity, which also rounds to the next power of two, states:

The vector will be able to hold at least capacity elements without reallocating. This method is allowed to allocate for more elements than capacity. If capacity is 0, the vector will not allocate.

...

If it is important to know the exact allocated capacity of a Vec, always use the capacity method after construction.

The broadcast channel docs could probably use similar language.