From 6aab42c39060c7aa39d96c7a265ddc661cea2ed8 Mon Sep 17 00:00:00 2001
From: "Dr. David von Oheimb" <David.von.Oheimb@siemens.com>
Date: Mon, 25 Jan 2021 20:44:39 +0100
Subject: [PATCH] OSSL_HTTP_REQ_CTX.pod and OSSL_HTTP_transfer.pod: various
 improvements

Reviewed-by: Paul Dale <pauli@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/13960)
---
 doc/man3/OSSL_HTTP_REQ_CTX.pod  | 31 +++++++++++++++++++------------
 doc/man3/OSSL_HTTP_transfer.pod | 14 ++++++++------
 2 files changed, 27 insertions(+), 18 deletions(-)

diff --git a/doc/man3/OSSL_HTTP_REQ_CTX.pod b/doc/man3/OSSL_HTTP_REQ_CTX.pod
index ec18e36d95..0b730b4e17 100644
--- a/doc/man3/OSSL_HTTP_REQ_CTX.pod
+++ b/doc/man3/OSSL_HTTP_REQ_CTX.pod
@@ -56,8 +56,8 @@ should be preferred.
 OSSL_HTTP_REQ_CTX_new() allocates a new HTTP request context structure,
 which gets populated with the B<BIO> to send the request to (I<wbio>),
 the B<BIO> to read the response from (I<rbio>, which may be equal to I<wbio>),
-the maximum expected response header line length (I<maxline>, where any
-zero or less indicates using the B<HTTP_DEFAULT_MAX_LINE_LENGTH> of 4KiB;
+the maximum expected response header line length (I<maxline>, where a value <= 0
+indicates that the B<HTTP_DEFAULT_MAX_LINE_LENGTH> of 4KiB should be used;
 this length is also used as the number of content bytes read at a time),
 the request method (I<method_POST>, which may be 1 to indicate that the C<POST>
 method is to be used, or 0 to indicate that the C<GET> method is to be used),
@@ -90,27 +90,31 @@ For example, to add a C<Host> header for C<example.com> you would call:
 
  OSSL_HTTP_REQ_CTX_add1_header(ctx, "Host", "example.com");
 
-OSSL_HTTP_REQ_CTX_i2d() finalizes the HTTP request context by adding the DER
-encoding of I<req>, using the ASN.1 template I<it> to do the encoding.  The
-HTTP header C<Content-Length> is automatically filled out, and if
+OSSL_HTTP_REQ_CTX_i2d() finalizes the HTTP request context by adding
+the DER encoding of I<req>, using the ASN.1 template I<it> to do the encoding.
+The HTTP header C<Content-Length> is automatically filled out, and if
 I<content_type> isn't NULL, the HTTP header C<Content-Type> is also added with
 its content as value.  All of this ends up in the internal memory B<BIO>.
 This requires that I<method_POST> was 1 in the OSSL_HTTP_REQ_CTX_new() call.
 
-OSSL_HTTP_REQ_CTX_nbio() attempts the exchange of request and response via HTTP,
-using the I<rbio> and I<wbio> that were given in the OSSL_HTTP_REQ_CTX_new()
-call.  When successful, the contents of the internal memory B<BIO> is replaced
-with the contents of the HTTP response, without the response headers.
+OSSL_HTTP_REQ_CTX_nbio() attempts to send the request prepared I<rctx>
+and gathering the response via HTTP, using the I<rbio> and I<wbio>
+that were given when calling OSSL_HTTP_REQ_CTX_new().
+When successful, the contents of the internal memory B<BIO> contains
+the contents of the HTTP response, without the response headers.
 It may need to be called again if its result is -1, which indicates
 L<BIO_should_retry(3)>.  In such a case it is advisable to sleep a little in
-between to prevent a busy loop.
+between using L<BIO_wait(3)> on the read BIO to prevent a busy loop.
 
 OSSL_HTTP_REQ_CTX_sendreq_d2i() calls OSSL_HTTP_REQ_CTX_nbio(), possibly
 several times until a timeout is reached, and DER decodes the received
 response using the ASN.1 template I<it>.
 
-OSSL_HTTP_REQ_CTX_get0_mem_bio() returns the internal memory B<BIO>.  This can
-be used to affect the HTTP request text.  I<Use with caution!>
+OSSL_HTTP_REQ_CTX_get0_mem_bio() returns the internal memory B<BIO>.
+Before sending the request, this could used to modify the HTTP request text.
+I<Use with caution!>
+After receiving a response via HTTP, the BIO represents
+the current state of reading the response headers and contents.
 
 OSSL_HTTP_REQ_CTX_set_max_response_length() sets the maximum allowed
 response content length for I<rctx> to I<len>. If not set or I<len> is 0
@@ -173,6 +177,9 @@ OSSL_HTTP_REQ_CTX_get0_mem_bio() returns the internal memory B<BIO>.
 
 =head1 SEE ALSO
 
+L<BIO_should_retry(3)>,
+L<BIO_wait(3)>,
+L<OSSL_HTTP_get(3)>,
 L<OSSL_HTTP_transfer(3)>
 
 =head1 COPYRIGHT
diff --git a/doc/man3/OSSL_HTTP_transfer.pod b/doc/man3/OSSL_HTTP_transfer.pod
index 33ae25685b..cb38d0124f 100644
--- a/doc/man3/OSSL_HTTP_transfer.pod
+++ b/doc/man3/OSSL_HTTP_transfer.pod
@@ -123,10 +123,11 @@ while using a proxy for HTTPS connections requires a suitable callback function
 such as OSSL_HTTP_proxy_connect(), described below.
 
 The I<maxline> parameter specifies the response header maximum line length,
-where a value <= 0 indicates using the B<HTTP_DEFAULT_MAX_LINE_LENGTH> of 4KiB.
-This length is also used as the number of content bytes read at a time.
+where a value <= 0 indicates that the B<HTTP_DEFAULT_MAX_LINE_LENGTH> of 4KiB
+should be used.
+This length is also used as the number of content bytes that are read at a time.
 The I<max_resp_len> parameter specifies the maximum response length,
-where 0 indicates the B<HTTP_DEFAULT_MAX_RESP_LEN>, which currently is 100 KiB.
+where 0 indicates B<HTTP_DEFAULT_MAX_RESP_LEN>, which currently is 100 KiB.
 
 An ASN.1-encoded response is expected by OSSL_HTTP_get_asn1() and
 OSSL_HTTP_post_asn1(), while for OSSL_HTTP_get() or OSSL_HTTP_transfer()
@@ -218,9 +219,10 @@ other HTTP client implementations such as wget, curl, and git.
 
 =head1 RETURN VALUES
 
-OSSL_HTTP_get(), OSSL_HTTP_get_asn1(), OSSL_HTTP_post_asn1(), and
-OSSL_HTTP_transfer() return on success the data received via HTTP, else NULL.
-Error conditions include connection/transfer timeout, parse errors, etc.
+On success, OSSL_HTTP_get(), OSSL_HTTP_get_asn1(), OSSL_HTTP_post_asn1(), and
+OSSL_HTTP_transfer() return a memory BIO containing the data received via HTTP.
+This must be freed by the caller. On failure, NULL is returned.
+Failure conditions include connection/transfer timeout, parse errors, etc.
 
 OSSL_HTTP_proxy_connect() and OSSL_HTTP_parse_url()
 return 1 on success, 0 on error.