Minor: Clarify documentaiton on NullBufferBuilder::allocated_size

[alamb]

Which issue does this PR close?

Related to

• refactor: switch BooleanBufferBuilder to NullBufferBuilder in MaybeNullBufferBuilder datafusion#14504

Rationale for this change

@Chen-Yuan-Lai found in apache/datafusion#14504 that NullBufferBuilder::allocated_size actually reports the size in bits, not bytes -- nice eyes!

What changes are included in this PR?

Update the documentation to reflect what the code does

1. Add an example onBooleanBufferBuilder::capacity to verify it is in terms of bits

Are there any user-facing changes?

Better docs

[alamb]

The key detail is that this function returns the value in bits (not bytes)

[alamb]

This documentation is wrong -- as it uses capacity() directly which returns a size in bits

I actually think it would be better if we had a function that returned allocated size in bytes (maybe we can deprecate this one and make a new one like allocated_bytes() or something for clarity.

[Jefffrey]

This is something I also noticed in #7082

One thing to note is that NullBufferBuilder::allocated_size() is used here:

arrow-rs/arrow-array/src/builder/generic_bytes_view_builder.rs

Lines 397 to 408 in 92cfd99

	/// Return the allocated size of this builder in bytes, useful for memory accounting.
	pub fn allocated_size(&self) -> usize {
	let views = self.views_builder.capacity() * std::mem::size_of::<u128>();
	let null = self.null_buffer_builder.allocated_size();
	let buffer_size = self.completed.iter().map(|b| b.capacity()).sum::<usize>();
	let in_progress = self.in_progress.capacity();
	let tracker = match &self.string_tracker {
	Some((ht, _)) => ht.capacity() * std::mem::size_of::<usize>(),
	None => 0,
	};
	buffer_size + in_progress + tracker + views + null
	}

And I think it's used with assumption it provides bytes not bits, so may need adjustment.

[Jefffrey]

Maybe add a small note here explaining why it over allocates?