unclear how BufRead::consume interacts with fill_buf

Location

BufRead::consume

Summary

It is not clear if consume should mutate the stream to make fill_buf return less bytes, or if fill_buf can return identical contents after the buffer is partially consumed.

The implementation of BufRead on &[u8] modifies what is returned by fill_buf, so it is at the very least allowed.

As such, consume must be called with the number of bytes that are consumed from this buffer to ensure that the bytes are never returned twice.

This could be interpreted as requiring this behavior, but it could also be interpreted as talking about the behavior of read, since that is the subject of that paragraph. Additionally, this is part of the fill_buf documentation, and it would be somewhat odd to describe what consume must do in the documentation of a different method.

Start at the BufRead::consume and fill_buf documentation linked in the issue, reading the surrounding guidance about returned bytes and read. Clarify whether consume must change subsequent fill_buf results or only account for bytes already consumed, so the documentation gives an unambiguous contract.