Extend documentation of PipeReader.AdvanceTo

[lg2de]

I started discussion on extension of documentation of PipeReader.AdvanceTo in dotnet/runtime#38277.

For the overloads

1. AdvanceTo(SequencePosition)
2. AdvanceTo(SequencePosition, SequencePosition)

I would like to change as follows:

• Remarks for both overloads
  • The processing of the buffer distinguishes between consumed and examined. Consumed data can be released. The amount of examined data communicates to the pipeline when it should signal more data is available.
  • The memory for the consumed data will be released and no longer available. So, the buffer previously returned from ReadAsync(CancellationToken) must not be accessed after this call.
• Additional remarks for the overload (1)
  • The specified position marks the end of the buffer section which is consumed and examined. Remaining buffer is kept and immediately provided as unexamined at the next call to ReadAsync.
• Additional remarks for the overload (2)
  • The specified positions mark the first buffer section to be consumed and the second buffer section to be examined. The examined position must be greater or equal to the consumed position. The buffer not yet consumed is kept.
  • Specifying a buffer section to be not yet examined causes the next call to ReadAsync to return immediately the whole remaining buffer. If all data has been examined, the end position of current buffer should be specified.
• Summary of the overload (2)
  • Moves forward the pipeline's read cursor to after the consumed data, marking the data as processed and examined.

Would you accept such an PR even the documentation has been improved already by #4311?

[carlossanlop]

Tagging area owners @davidfowl @halter73 @jkotalik for triaging.