Revamp the manual, one page per function/message

1 files changed, 92 insertions, 0 deletions

diff --git a/doc/src/manual/gun.head.asciidoc b/doc/src/manual/gun.head.asciidoc
new file mode 100644
index 0000000..3d92e38
--- /dev/null
+++ b/doc/src/manual/gun.head.asciidoc
@@ -0,0 +1,92 @@
+= gun:head(3)
+
+== Name
+
+gun:head - Get headers of a resource representation
+
+== Description
+
+[source,erlang]
+----
+head(ConnPid, Path)
+    -> head(ConnPid, Path, [], #{}).
+
+head(ConnPid, Path, Headers)
+    -> head(ConnPid, Path, Headers, #{})
+
+head(ConnPid, Path, Headers, ReqOpts)
+    -> StreamRef
+
+ConnPid   :: pid()
+Path      :: iodata()
+Headers   :: [{binary(), iodata()}]
+ReqOpts   :: gun:req_opts()
+StreamRef :: reference()
+----
+
+Get headers of a resource representation.
+
+This function performs the same operation as
+link:man:gun:get(3)[gun:get(3)], except the server will not
+send the resource representation, only the response's status
+code and headers.
+
+While servers are supposed to send the same headers as for
+a GET request, they sometimes will not. For example the
+`content-length` header may be dropped from the response.
+
+== Arguments
+
+ConnPid::
+
+The pid of the Gun connection process.
+
+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
+
+* *1.0*: Function introduced.
+
+== Examples
+
+.Get headers of a resource representation
+[source,erlang]
+----
+StreamRef = gun:head(ConnPid, "/articles", [
+    {<<"accept">>, <<"text/html;q=1.0, application/xml;q=0.1">>}
+]).
+----
+
+.Get headers of a resource representation with request options
+[source,erlang]
+----
+StreamRef = gun:head(ConnPid, "/articles", [], #{
+    reply_to => ReplyToPid
+}).
+----
+
+== See also
+
+link:man:gun(3)[gun(3)],
+link:man:gun:get(3)[gun:head(3)],
+link:man:gun:await(3)[gun:await(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)]