What is Allocator::by_ref for?

That doesn't really explain much. The iterator by_ref has all the same oddities. It seems to do nothing other than return a simple borrow and its documentation also talks about returning an adapter of some kind, which it does not seem to do.

Are these just convenience methods with oddly worded documentation?