Separate request/4,5,6 into headers/4,5 and request/5,6

This cleaner separation gets rid of the implicit body check
that was causing issues for many users. Now the body is
either given explicitly or it is expected via future
gun:data/3 calls.

1 files changed, 86 insertions, 0 deletions

diff --git a/doc/src/manual/gun.headers.asciidoc b/doc/src/manual/gun.headers.asciidoc
new file mode 100644
index 0000000..bab1b82
--- /dev/null
+++ b/doc/src/manual/gun.headers.asciidoc
@@ -0,0 +1,86 @@
+= gun:headers(3)
+
+== Name
+
+gun:headers - Initiate the given request
+
+== Description
+
+[source,erlang]
+----
+headers(ConnPid, Method, Path, Headers)
+    -> headers(ConnPid, Method, Path, Headers, #{})
+
+headers(ConnPid, Method, Path, Headers, ReqOpts)
+    -> StreamRef
+
+ConnPid   :: pid()
+Method    :: binary()
+Path      :: iodata()
+Headers   :: [{binary(), iodata()}]
+ReqOpts   :: gun:req_opts()
+StreamRef :: reference()
+----
+
+Initiate the given request.
+
+This is a general purpose function that should only be
+used when other method-specific functions do not apply.
+
+The function `headers/4,5` initiates a request but does
+not send the request body. It must be sent separately
+using link:man:gun:data(3)[gun:data(3)].
+
+== Arguments
+
+ConnPid::
+
+The pid of the Gun connection process.
+
+Method::
+
+Method to be used for the request.
+
+Path::
+
+Path to the resource.
+
+Headers::
+
+Additional request headers.
+
+ReqOpts::
+
+Request options.
+
+== Return value
+
+A reference that identifies the newly created stream is
+returned. It is this reference that must be passed in
+subsequent calls and will be received in messages related
+to this new stream.
+
+== Changelog
+
+* *2.0*: Function introduced.
+
+== Examples
+
+.Initiate a request
+[source,erlang]
+----
+StreamRef = gun:headers(ConnPid, <<"PUT">>,
+    "/lang/fr_FR/hello",
+    [{<<"content-type">>, <<"text/plain">>}]).
+----
+
+== See also
+
+link:man:gun(3)[gun(3)],
+link:man:gun:request(3)[gun:request(3)],
+link:man:gun:await(3)[gun:await(3)],
+link:man:gun:await_body(3)[gun:await_body(3)],
+link:man:gun_push(3)[gun_push(3)],
+link:man:gun_inform(3)[gun_inform(3)],
+link:man:gun_response(3)[gun_response(3)],
+link:man:gun_data(3)[gun_data(3)]