SI-8910 BitSet sometimes uses exponential memory.

Because of an off-by-one error in scala.collection.mutable.BitSet, where a
function (ensureCapacity) is passed a list length instead of an index, when
^=, &=, |=, or &~= are passed BitSets with the same internal capacity as the
set the method is being invoked on, the size of the first BitSet is needlessly
doubled.

This patch simply changes the ensureCapacity calls to pass the last index of
the list, instead of the raw length. In addition, add documentation to
ensureCapacity to try and stop something similar from happening in the future.