1 files changed, 115 insertions, 0 deletions
diff --git a/doc/src/manual/cowboy_req.set_resp_cookie.asciidoc b/doc/src/manual/cowboy_req.set_resp_cookie.asciidoc
new file mode 100644
index 0000000..75126b1
--- /dev/null
+++ b/doc/src/manual/cowboy_req.set_resp_cookie.asciidoc
@@ -0,0 +1,115 @@
+= cowboy_req:set_resp_cookie(3)
+
+== Name
+
+cowboy_req:set_resp_cookie - Set a cookie
+
+== Description
+
+[source,erlang]
+----
+set_resp_cookie(Name, Value, Req :: cowboy_req:req())
+    -> set_resp_cookie(Name, Value, [], Req)
+
+set_resp_cookie(Name, Value, Opts, Req :: cowboy_req:req())
+    -> Req
+
+Name  :: iodata()                  %% case sensitive
+Value :: iodata()                  %% case sensitive
+Opts  :: cow_cookie:cookie_opts()
+----
+
+// @todo I am not particularly happy about the fact that the name is iodata().
+
+Set a cookie to be sent with the response.
+
+Note that cookie names are case sensitive.
+
+== Arguments
+
+Name::
+
+Cookie name.
+
+Value::
+
+Cookie value.
+
+Opts::
+
+Optional cookie options.
+
+Req::
+
+The Req object.
+
+== Return value
+
+A new Req object is returned.
+
+The returned Req object must be used from that point onward,
+otherwise the cookie will not be sent in the response.
+
+== Changelog
+
+* *2.0*: `set_resp_cookie/3` introduced as an alias to `set_resp_cookie/4` with no options.
+* *1.0*: Function introduced.
+
+== Examples
+
+.Set a session cookie
+[source,erlang]
+----
+SessionID = base64:encode(crypto:strong_rand_bytes(32)),
+Req = cowboy_req:set_resp_cookie(<<"sessionid">>, SessionID, Req0).
+----
+
+.Set a cookie with an expiration time
+[source,erlang]
+----
+Req = cowboy_req:set_resp_cookie(<<"lang">>, <<"fr-FR">>, [
+    {max_age, 3600}
+], Req0).
+----
+
+.Delete a cookie
+[source,erlang]
+----
+Req = cowboy_req:set_resp_cookie(<<"sessionid">>, <<>>, [
+    {max_age, 0}
+], Req0).
+----
+
+.Set a cookie for a specific domain and path
+[source,erlang]
+----
+Req = cowboy_req:set_resp_cookie(<<"inaccount">>, <<"1">>, [
+    {domain, "my.example.org"},
+    {path, "/account"}
+], Req0).
+----
+
+.Restrict a cookie to HTTPS
+[source,erlang]
+----
+SessionID = base64:encode(crypto:strong_rand_bytes(32)),
+Req = cowboy_req:set_resp_cookie(<<"sessionid">>, SessionID, [
+    {secure, true}
+], Req0).
+----
+
+.Restrict a cookie to HTTP
+[source,erlang]
+----
+SessionID = base64:encode(crypto:strong_rand_bytes(32)),
+Req = cowboy_req:set_resp_cookie(<<"sessionid">>, SessionID, [
+    {http_only, true}
+], Req0).
+----
+
+== See also
+
+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:reply(3)[cowboy_req:reply(3)],
+link:man:cowboy_req:stream_reply(3)[cowboy_req:stream_reply(3)]