Add manual for cow_cookie

7 files changed, 222 insertions, 2 deletions

diff --git a/Makefile b/Makefile
index ca191c0..59da917 100644
--- a/Makefile
+++ b/Makefile
@@ -18,6 +18,8 @@ DIALYZER_OPTS = -Werror_handling -Wunmatched_returns
 
 LOCAL_DEPS = crypto
 
+DOC_DEPS = asciideck
+
 TEST_DEPS = $(if $(CI_ERLANG_MK),ci.erlang.mk) horse proper
 dep_horse = git https://github.com/ninenines/horse.git master
 
diff --git a/README.asciidoc b/README.asciidoc
index ee3065f..8b6a5ad 100644
--- a/README.asciidoc
+++ b/README.asciidoc
@@ -5,7 +5,8 @@ Cowlib is a support library for manipulating Web protocols.
 == Goals
 
 Cowlib provides libraries for parsing and building messages
-for various Web protocols, including SPDY, HTTP and Websocket.
+for various Web protocols, including HTTP/1.1, HTTP/2 and
+Websocket.
 
 It is optimized for completeness rather than speed. No value
 is ignored, they are all returned.
diff --git a/doc/src/manual/cow_cookie.asciidoc b/doc/src/manual/cow_cookie.asciidoc
new file mode 100644
index 0000000..0717299
--- /dev/null
+++ b/doc/src/manual/cow_cookie.asciidoc
@@ -0,0 +1,78 @@
+= cow_cookie(3)
+
+== Name
+
+cow_cookie - Cookies
+
+== Description
+
+The module `cow_cookie` provides functions for parsing
+and manipulating cookie headers.
+
+== Exports
+
+* link:man:cow_cookie:parse_cookie(3)[cow_cookie:parse_cookie(3)] - Parse a cookie header
+* link:man:cow_cookie:setcookie(3)[cow_cookie:setcookie(3)] - Generate a set-cookie header
+
+== Types
+
+=== cookie_opts()
+
+[source,erlang]
+----
+cookie_opts() :: [Option]
+
+Option :: {domain, binary()}
+        | {http_only, boolean()}
+        | {max_age, non_neg_integer()}
+        | {path, binary()}
+        | {same_site, lax | strict}
+        | {secure, boolean()}
+----
+
+Options for the set-cookie header. They are added to the
+header as attributes. More information about the options
+can be found in https://tools.ietf.org/html/rfc6265[RFC 6265].
+
+The following options are defined:
+
+domain::
+
+Hosts to which the cookie will be sent. By default it will
+only be sent to the origin server.
+
+http_only::
+
+Whether the cookie should be restricted to HTTP requests, or
+it should also be exposed to other APIs, for example Javascript.
+By default there are no restrictions.
+
+max_age::
+
+Maximum lifetime of the cookie, in seconds. By default the
+cookie is kept for the duration of the session.
+
+path::
+
+Path to which the cookie will be sent. By default it will
+be sent to the current "directory" of the effective request URI.
+
+same_site::
+
+Whether the cookie should be sent along with cross-site
+requests. This header is currently non-standard but is in
+the process of being standardized. Please refer to the
+https://tools.ietf.org/html/draft-ietf-httpbis-rfc6265bis-03#section-4.1.2.7[RFC 6265 (bis) draft]
+for details.
+
+secure::
+
+Whether the cookie should be sent only on secure channels
+(for example TLS). Note that this does not guarantee the
+integrity of the cookie, only its confidentiality during
+transfer. By default there are no restrictions.
+
+== See also
+
+link:man:cowlib(7)[cowlib(7)],
+https://tools.ietf.org/html/rfc6265[RFC 6265]
diff --git a/doc/src/manual/cow_cookie.parse_cookie.asciidoc b/doc/src/manual/cow_cookie.parse_cookie.asciidoc
new file mode 100644
index 0000000..0b7393e
--- /dev/null
+++ b/doc/src/manual/cow_cookie.parse_cookie.asciidoc
@@ -0,0 +1,44 @@
+= cow_cookie:parse_cookie(3)
+
+== Name
+
+cow_cookie:parse_cookie - Parse a cookie header
+
+== Description
+
+[source,erlang]
+----
+parse_cookie(Cookie :: binary())
+    -> [{binary(), binary()}]
+----
+
+Parse a cookie header.
+
+== Arguments
+
+Cookie::
+
+The cookie header value.
+
+== Return value
+
+A list of cookie name/value pairs is returned on success.
+
+An exception is thrown in the event of a parse error.
+
+== Changelog
+
+* *1.0*: Function introduced.
+
+== Examples
+
+.Parse a cookie header
+[source,erlang]
+----
+Cookies = cow_cookie:parse_cookie(CookieHd).
+----
+
+== See also
+
+link:man:cow_cookie(3)[cow_cookie(3)],
+link:man:cow_cookie:setcookie(3)[cow_cookie:setcookie(3)]
diff --git a/doc/src/manual/cow_cookie.setcookie.asciidoc b/doc/src/manual/cow_cookie.setcookie.asciidoc
new file mode 100644
index 0000000..ab2d466
--- /dev/null
+++ b/doc/src/manual/cow_cookie.setcookie.asciidoc
@@ -0,0 +1,55 @@
+= cow_cookie:setcookie(3)
+
+== Name
+
+cow_cookie:setcookie - Generate a set-cookie header
+
+== Description
+
+[source,erlang]
+----
+setcookie(Name  :: iodata(),
+          Value :: iodata(),
+          Opts  :: cow_cookie:cookie_opts())
+    -> iolist()
+----
+
+Generate a set-cookie header.
+
+== Arguments
+
+Name::
+
+Cookie name.
+
+Value::
+
+Cookie value.
+
+Opts::
+
+Options added to the set-cookie header as attributes.
+
+== Return value
+
+An iolist with the generated set-cookie header value.
+
+== Changelog
+
+* *1.0*: Function introduced.
+
+== Examples
+
+.Generate a set-cookie header
+[source,erlang]
+----
+SetCookie = cow_cookie:setcookie(<<"sessionid">>, ID, #{
+    http_only => true,
+    secure => true
+}).
+----
+
+== See also
+
+link:man:cow_cookie(3)[cow_cookie(3)],
+link:man:cow_cookie:parse_cookie(3)[cow_cookie:parse_cookie(3)]
diff --git a/doc/src/manual/cowlib_app.asciidoc b/doc/src/manual/cowlib_app.asciidoc
new file mode 100644
index 0000000..5e659d2
--- /dev/null
+++ b/doc/src/manual/cowlib_app.asciidoc
@@ -0,0 +1,40 @@
+= cowlib(7)
+
+== Name
+
+cowlib - Support library for manipulating Web protocols
+
+== Description
+
+Cowlib provides libraries for parsing and building messages
+for various Web protocols, including HTTP/1.1, HTTP/2  and
+Websocket.
+
+It is optimized for completeness rather than speed. No value
+is ignored, they are all returned.
+
+== Modules
+
+* link:man:cow_cookie(3)[cow_cookie(3)] - Cookies
+
+== Dependencies
+
+* crypto - Crypto functions
+
+All these applications must be started before the `cowlib`
+application. To start Cowlib and all dependencies at once:
+
+[source,erlang]
+----
+{ok, _} = application:ensure_all_started(cowlib).
+----
+
+== Environment
+
+The `cowlib` application does not define any application
+environment configuration parameters.
+
+== See also
+
+link:man:cowboy(7)[cowboy(7)],
+link:man:gun(7)[gun(7)]
diff --git a/src/cow_cookie.erl b/src/cow_cookie.erl
index b53fa35..199b64b 100644
--- a/src/cow_cookie.erl
+++ b/src/cow_cookie.erl
@@ -180,7 +180,7 @@ parse_cookie_error_test_() ->
 %% Initial binary implementation:
 %%   * Copyright 2011 Thomas Burdick <[email protected]>
 
--spec setcookie(iodata(), iodata(), cookie_opts()) -> iodata().
+-spec setcookie(iodata(), iodata(), cookie_opts()) -> iolist().
 setcookie(Name, Value, Opts) ->
 	nomatch = binary:match(iolist_to_binary(Name), [<<$=>>, <<$,>>, <<$;>>,
 			<<$\s>>, <<$\t>>, <<$\r>>, <<$\n>>, <<$\013>>, <<$\014>>]),