Improve the manual for the new resp_header functions

doc/src/manual/cowboy_req.asciidoc

@@ -67,11 +67,11 @@ Request body:
 Response:
 
 * link:man:cowboy_req:set_resp_cookie(3)[cowboy_req:set_resp_cookie(3)] - Set a cookie
-* link:man:cowboy_req:resp_header(3)[cowboy_req:resp_header(3)] - Access the named HTTP header set for the response
-* link:man:cowboy_req:resp_headers(3)[cowboy_req:resp_headers(3)] - Access HTTP headers set for the response
 * link:man:cowboy_req:set_resp_header(3)[cowboy_req:set_resp_header(3)] - Set a response header
 * link:man:cowboy_req:set_resp_headers(3)[cowboy_req:set_resp_headers(3)] - Set several response headers
 * link:man:cowboy_req:has_resp_header(3)[cowboy_req:has_resp_header(3)] - Is the given response header set?
+* link:man:cowboy_req:resp_header(3)[cowboy_req:resp_header(3)] - Response header
+* link:man:cowboy_req:resp_headers(3)[cowboy_req:resp_headers(3)] - Response headers
 * link:man:cowboy_req:delete_resp_header(3)[cowboy_req:delete_resp_header(3)] - Delete a response header
 * link:man:cowboy_req:set_resp_body(3)[cowboy_req:set_resp_body(3)] - Set the response body
 * link:man:cowboy_req:has_resp_body(3)[cowboy_req:has_resp_body(3)] - Is there a response body?

doc/src/manual/cowboy_req.delete_resp_header.asciidoc

@@ -52,4 +52,7 @@ Req = cowboy_req:delete_resp_header(<<"content-type">>, Req0),
 
 link:man:cowboy_req(3)[cowboy_req(3)],
 link:man:cowboy_req:set_resp_header(3)[cowboy_req:set_resp_header(3)],
-link:man:cowboy_req:has_resp_header(3)[cowboy_req:has_resp_header(3)]
+link:man:cowboy_req:set_resp_headers(3)[cowboy_req:set_resp_headers(3)],
+link:man:cowboy_req:has_resp_header(3)[cowboy_req:has_resp_header(3)],
+link:man:cowboy_req:resp_header(3)[cowboy_req:resp_header(3)],
+link:man:cowboy_req:resp_headers(3)[cowboy_req:resp_headers(3)]

doc/src/manual/cowboy_req.has_resp_header.asciidoc

@@ -51,4 +51,7 @@ true = cowboy_req:has_resp_header(<<"content-type">>, Req).
 
 link:man:cowboy_req(3)[cowboy_req(3)],
 link:man:cowboy_req:set_resp_header(3)[cowboy_req:set_resp_header(3)],
+link:man:cowboy_req:set_resp_headers(3)[cowboy_req:set_resp_headers(3)],
+link:man:cowboy_req:resp_header(3)[cowboy_req:resp_header(3)],
+link:man:cowboy_req:resp_headers(3)[cowboy_req:resp_headers(3)],
 link:man:cowboy_req:delete_resp_header(3)[cowboy_req:delete_resp_header(3)]

doc/src/manual/cowboy_req.reply.asciidoc

@@ -29,7 +29,8 @@ While header names are case insensitive, Cowboy requires them
 to be given as lowercase to function properly.
 
 Cowboy does not allow duplicate header names. Headers set
-by this function may overwrite those set by `set_resp_header/3`.
+by this function may overwrite those set by `set_resp_header/3`
+and `set_resp_headers/2`.
 
 Use link:man:cowboy_req:set_resp_cookie(3)[cowboy_req:set_resp_cookie(3)]
 instead of this function to set cookies.
@@ -110,6 +111,7 @@ Req = cowboy_req:reply(200, #{
 link:man:cowboy_req(3)[cowboy_req(3)],
 link:man:cowboy_req:set_resp_cookie(3)[cowboy_req:set_resp_cookie(3)],
 link:man:cowboy_req:set_resp_header(3)[cowboy_req:set_resp_header(3)],
+link:man:cowboy_req:set_resp_headers(3)[cowboy_req:set_resp_headers(3)],
 link:man:cowboy_req:set_resp_body(3)[cowboy_req:set_resp_body(3)],
 link:man:cowboy_req:stream_reply(3)[cowboy_req:stream_reply(3)],
 link:man:cowboy_req:push(3)[cowboy_req:push(3)]

doc/src/manual/cowboy_req.resp_header.asciidoc

@@ -2,7 +2,7 @@
 
 == Name
 
-cowboy_req:resp_header - Access the named HTTP header set for the response
+cowboy_req:resp_header - Response header
 
 == Description
 
@@ -11,18 +11,26 @@ cowboy_req:resp_header - Access the named HTTP header set for the response
 resp_header(Name, Req)          -> resp_header(Name, Req, undefined)
 resp_header(Name, Req, Default) -> binary() | Default
 
-Name    :: binary()
+Name    :: binary()          %% lowercase; case insensitive
 Req     :: cowboy_req:req()
 Default :: any()
 ----
 
-Return the currently set response header value for the given HTTP header.
+Return the value for the given response header.
+
+The response header must have been set previously using
+link:man:cowboy_req:set_resp_header(3)[cowboy_req:set_resp_header(3)] or
+link:man:cowboy_req:set_resp_headers(3)[cowboy_req:set_resp_headers(3)].
+
+The header name must be given as a lowercase binary string.
+While header names are case insensitive, Cowboy requires them
+to be given as lowercase to function properly.
 
 == Arguments
 
 Name::
 
-Desired response HTTP header name as a binary.
+Desired response header name as a lowercase binary string.
 
 Req::
 
@@ -34,7 +42,8 @@ Default value returned when the header is missing.
 
 == Return value
 
-The binary value for the given HTTP header name.
+The header value is returned as a binary string. When the
+header is missing, the default argument is returned.
 
 == Changelog
 
@@ -42,20 +51,21 @@ The binary value for the given HTTP header name.
 
 == Examples
 
-.Get the response header with the given name
+.Get the content-type response header
 [source,erlang]
 ----
-HeaderValue = cowboy_req:resp_header(<<"x-test-header">>, Req).
+Type = cowboy_req:resp_header(<<"content-type">>, Req).
 ----
 
-.Get the response header with the given name and a default
+.Get the content-type response header with a default value
 [source,erlang]
 ----
-HeaderValue = cowboy_req:resp_header(<<"x-test-header">>, Req, <<"bar">>).
+Type = cowboy_req:resp_header(<<"content-type">>, Req, <<"text/html">>).
 ----
 
 == See also
 
 link:man:cowboy_req(3)[cowboy_req(3)],
-link:man:cowboy_req:set_resp_headers(3)[cowboy_req:resp_headers(3)]
-link:man:cowboy_req:set_resp_header(3)[cowboy_req:set_resp_header(3)]
+link:man:cowboy_req:resp_headers(3)[cowboy_req:resp_headers(3)],
+link:man:cowboy_req:set_resp_header(3)[cowboy_req:set_resp_header(3)],
+link:man:cowboy_req:set_resp_headers(3)[cowboy_req:set_resp_headers(3)]

doc/src/manual/cowboy_req.resp_headers.asciidoc

@@ -2,18 +2,16 @@
 
 == Name
 
-cowboy_req:resp_headers - Access HTTP headers set for the response
+cowboy_req:resp_headers - Response headers
 
 == Description
 
 [source,erlang]
 ----
-resp_headers(Req) -> cowboy:http_headers()
-
-Req :: cowboy_req:req()
+resp_headers(Req :: cowboy_req:req()) -> cowboy:http_headers()
 ----
 
-Return all HTTP response headers.
+Return all response headers.
 
 == Arguments
 
@@ -25,7 +23,6 @@ The Req object.
 
 Headers are returned as a map with keys being lowercase
 binary strings, and values as binary strings.
-If no response headers have been added the empty map is returned.
 
 == Changelog
 
@@ -42,4 +39,6 @@ Headers = cowboy_req:resp_headers(Req).
 == See also
 
 link:man:cowboy_req(3)[cowboy_req(3)],
-link:man:cowboy_req:set_resp_headers(3)[cowboy_req:set_resp_headers(3)]
+link:man:cowboy_req:resp_header(3)[cowboy_req:resp_header(3)],
+link:man:cowboy_req:set_resp_header(3)[cowboy_req:set_resp_header(3)],
+link:man:cowboy_req:set_resp_headers(3)[cowboy_req:set_resp_headers(3)]

doc/src/manual/cowboy_req.set_resp_body.asciidoc

@@ -86,5 +86,6 @@ Req = cowboy_req:set_resp_body(<<>>, Req0).
 
 link:man:cowboy_req(3)[cowboy_req(3)],
 link:man:cowboy_req:set_resp_header(3)[cowboy_req:set_resp_header(3)],
+link:man:cowboy_req:set_resp_headers(3)[cowboy_req:set_resp_headers(3)],
 link:man:cowboy_req:reply(3)[cowboy_req:reply(3)],
 link:man:cowboy_req:stream_reply(3)[cowboy_req:stream_reply(3)]

doc/src/manual/cowboy_req.set_resp_cookie.asciidoc

@@ -111,5 +111,6 @@ Req = cowboy_req:set_resp_cookie(<<"sessionid">>, SessionID, [
 
 link:man:cowboy_req(3)[cowboy_req(3)],
 link:man:cowboy_req:set_resp_header(3)[cowboy_req:set_resp_header(3)],
+link:man:cowboy_req:set_resp_headers(3)[cowboy_req:set_resp_headers(3)],
 link:man:cowboy_req:reply(3)[cowboy_req:reply(3)],
 link:man:cowboy_req:stream_reply(3)[cowboy_req:stream_reply(3)]

doc/src/manual/cowboy_req.set_resp_header.asciidoc

@@ -72,7 +72,10 @@ Req = cowboy_req:set_resp_header(<<"allow">>,
 
 link:man:cowboy_req(3)[cowboy_req(3)],
 link:man:cowboy_req:set_resp_cookie(3)[cowboy_req:set_resp_cookie(3)],
+link:man:cowboy_req:set_resp_headers(3)[cowboy_req:set_resp_headers(3)],
 link:man:cowboy_req:has_resp_header(3)[cowboy_req:has_resp_header(3)],
+link:man:cowboy_req:resp_header(3)[cowboy_req:resp_header(3)],
+link:man:cowboy_req:resp_headers(3)[cowboy_req:resp_headers(3)],
 link:man:cowboy_req:delete_resp_header(3)[cowboy_req:delete_resp_header(3)],
 link:man:cowboy_req:reply(3)[cowboy_req:reply(3)],
 link:man:cowboy_req:stream_reply(3)[cowboy_req:stream_reply(3)]

doc/src/manual/cowboy_req.set_resp_headers.asciidoc

@@ -8,22 +8,32 @@ cowboy_req:set_resp_headers - Set several response headers
 
 [source,erlang]
 ----
-set_resp_headers(Headers, Req) -> cowboy_req:req()
+set_resp_headers(Headers, Req :: cowboy_req:req())
+    -> Req
 
 Headers :: cowboy:http_headers()
-Req     :: cowboy_req:req()
 ----
 
-Add all given headers to the response headers.
-If a given header key already exists in the currently set
-response-header map the given value will overwrite the old.
+Set several headers to be sent with the response.
+
+The header name must be given as a lowercase binary string.
+While header names are case insensitive, Cowboy requires them
+to be given as lowercase to function properly.
+
+Cowboy does not allow duplicate header names. Headers set
+by this function may be overwritten by those set from the
+reply functions. Likewise, headers set by this function may
+overwrite headers that were set previously.
+
+Use link:man:cowboy_req:set_resp_cookie(3)[cowboy_req:set_resp_cookie(3)]
+instead of this function to set cookies.
 
 == Arguments
 
 Headers::
 
-A map with keys and values as binary strings.
-Key values should be lowercase to function properly.
+Headers as a map with keys being lowercase binary strings,
+and values as binary strings.
 
 Req::
 
@@ -31,7 +41,10 @@ The Req object.
 
 == Return value
 
-A request object updated with the given response headers.
+A new Req object is returned.
+
+The returned Req object must be used from that point onward,
+otherwise the headers will not be sent in the response.
 
 == Changelog
 
@@ -39,13 +52,23 @@ A request object updated with the given response headers.
 
 == Examples
 
-.Get all response headers
+.Set several response headers
 [source,erlang]
 ----
-Req1 = cowboy_req:set_resp_headers(#{<<"x-header-test">> => <<"1">>}, Req0).
+Req = cowboy_req:set_resp_headers(#{
+    <<"content-type">>     => <<"text/html">>,
+    <<"content-encoding">> => <<"gzip">>
+}, Req0).
 ----
 
 == See also
 
 link:man:cowboy_req(3)[cowboy_req(3)],
-link:man:cowboy_req:resp_headers(3)[cowboy_req:resp_headers(3)]
+link:man:cowboy_req:set_resp_cookie(3)[cowboy_req:set_resp_cookie(3)],
+link:man:cowboy_req:set_resp_header(3)[cowboy_req:set_resp_header(3)],
+link:man:cowboy_req:has_resp_header(3)[cowboy_req:has_resp_header(3)],
+link:man:cowboy_req:resp_header(3)[cowboy_req:resp_header(3)],
+link:man:cowboy_req:resp_headers(3)[cowboy_req:resp_headers(3)],
+link:man:cowboy_req:delete_resp_header(3)[cowboy_req:delete_resp_header(3)],
+link:man:cowboy_req:reply(3)[cowboy_req:reply(3)],
+link:man:cowboy_req:stream_reply(3)[cowboy_req:stream_reply(3)]

doc/src/manual/cowboy_req.stream_reply.asciidoc

@@ -102,6 +102,7 @@ cowboy_req:stream_body(<<"World!\n">>, fin, Req).
 link:man:cowboy_req(3)[cowboy_req(3)],
 link:man:cowboy_req:set_resp_cookie(3)[cowboy_req:set_resp_cookie(3)],
 link:man:cowboy_req:set_resp_header(3)[cowboy_req:set_resp_header(3)],
+link:man:cowboy_req:set_resp_headers(3)[cowboy_req:set_resp_headers(3)],
 link:man:cowboy_req:reply(3)[cowboy_req:reply(3)],
 link:man:cowboy_req:stream_body(3)[cowboy_req:stream_body(3)],
 link:man:cowboy_req:push(3)[cowboy_req:push(3)]