Clarify that Response::content_length() is not derived from a Content-Length header in docs

[babolivier]

Something that's bitten me a few times (and that I see others get bitten by fairly often) is that the current documentation of Response::content_length() can lead users to believe its return value is a representation of the Content-Length header in responses. While the return value of this method and that header's value might happen to match in quite a few cases, it makes things very confusing when they don't, e.g. in HEAD requests.

This change updates the method's documentation (in both the blocking and async implementations) to clarify that its return value is calculated independently from the value of any Content-Length header, and directs users to use Response::headers() instead. It also removes the line about a lack of Content-Length header causing the method to "fail", since this doesn't match the implementation.

[seanmonstar]

This isn't quite true, either. It does depend on the content-length header. Without out, we can't know. But it doesn't only look at it. If the semantics of the request method or response status don't allow for a body, then it gets changed to 0.

Get the number of bytes that make up the response body, if known.

The value is based off the `content-length` header, but also depends on the
semantics of the request method or response status. For instance, a response
to a `HEAD` request may include a `content-length`, but the response body
will have exactly 0 bytes.

[babolivier]

As far as I can tell, this is not directly true, though. Strictly speaking, the content_length method seems to only look at the size of the response body, and not at any header - at least as far as I could see while following the source code.

It might be that the number of bytes reqwest (or the http crate) writes into the response body when receiving it is limited in some way by the received Content-Length header, but I'm failing to find the place where this is done either in reqwest or in http (though please feel free to point me to it, as I'm curious to figure this out).

Regardless, my point in opening this PR is more about informing the user of what this return value represents, i.e. the size of the response's body and not the direct value of the Content-Length header, without bothering users with implementation details that aren't relevant to them. Though I maybe could have phrased this differently. How would something like this sound to you?

This value does not directly represents the value of the Content-Length header, but rather the size of the response's body. To read the header's value, please use the Response::headers method instead.

[seanmonstar]

Strictly speaking, the content_length method seems to only look at the size of the response body, and not at any header

True, and the body type coming from hyper sets the size based on the content-length header.

I think the suggested block I provided last comment strikes a good balance with what it is, and also the most common reeason it isn't what they might have hoped. Well, but re-reading both again, I can see how what you suggested just now is even simpler. I don't know, we can try the simpler one if you prefer. Hopefully people will find it less confusing.

[babolivier]

Yeah, I think documenting implementation details in usage docs can be a slippery slope, both in terms of providing information most users might not really need, and the risk of this documentation getting out of sync with reality if the implementation (either in the "main" code or in a dependency) ends up changing.

I've updated the PR with my previous suggestion, let me know if it looks good to you, or if you'd like me to make changes to the wording 🙂

[babolivier]

(force-pushed to fix authorship and signatures in the commits)