Ergonomics of error list in `http::async_read` and `http::async_read_header` about beast HOT 4 CLOSED

The partial_message error is a parser error that occurs when the end of the file is reached in the middle of parsing a message. Are you suggesting that it doesn't seem like an error?

from beast.

I missed the sentence above the error bullet points that says "If the end of file error is received while reading from the stream, then the error returned from this function will be: "

When consulting a function's documentation, when I see a bullet list of error codes, my eyes immediately jump to them, and it's just natural for me to miss the context above those bullet points if it's buried in a long paragraph.

There should be a paragraph break before the "If the end of file error is received while reading from the stream, then the error returned from this function will be: " sentence.

In other words, it should appear like this:

This operation is implemented in terms of zero or more calls to the next layer's async_read_some function, and is known as a composed operation. The program must ensure that the stream performs no other reads until this operation completes. The implementation may read additional bytes from the stream that lie past the end of the message being read. These additional bytes are stored in the dynamic buffer, which must be preserved for subsequent reads.

If the end of file error is received while reading from the stream, then the error returned from this function will be:

• error::end_of_stream if no bytes were parsed, or
• error::partial_message if any bytes were parsed but the message was incomplete, otherwise:
• A successful result. The next attempt to read will return error::end_of_stream

from beast.

Yeah, this issue has already been addressed in #2793. The latest version of the documentation, does not have this problem: https://www.boost.org/doc/libs/master/libs/beast/doc/html/beast/ref/boost__beast__http__async_read/overload1.html

from beast.

I was just going to comment that the paragraph break I suggested was already in the source code.

I will consult the master branch for the documentation until the next release. Thank you for the prompt responses.

Closing as duplicate of #2792 .

from beast.