Add a manual

3 files changed, 287 insertions, 0 deletions

diff --git a/manual/gun.md b/manual/gun.md
new file mode 100644
index 0000000..ea624ea
--- /dev/null
+++ b/manual/gun.md
@@ -0,0 +1,258 @@
+gun
+===
+
+The `gun` module provides an asynchronous interface for
+connecting and communicating with Web servers over SPDY,
+HTTP or Websocket.
+
+Types
+-----
+
+### opts() = [{keepalive, pos_integer()}
+	| {retry, non_neg_integer()}
+	| {retry_timeout, pos_integer()}
+	| {type, ssl | tcp | tcp_spdy}].
+
+> Configuration for the connection.
+
+Option descriptions
+-------------------
+
+The default value is given next to the option name.
+
+ -  keepalive (5000)
+   -  Time between pings in milliseconds.
+ -  retry (5)
+   -  Number of times Gun will try to reconnect on failure before giving up.
+ -  retry_timeout (5000)
+   -  Time between retries in milliseconds.
+ -  type (ssl)
+   -  Whether to use SSL, plain TCP (for HTTP/Websocket) or SPDY over TCP.
+
+Exports
+-------
+
+### open(Host, Port) -> open(Host, Port, [])
+### open(Host, Port, Opts) -> {ok, ServerPid} | {error, any()}
+
+> Types:
+>  *  Host = inet:hostname()
+>  *  Port = inet:port_number()
+>  *  Opts = opts()
+>  *  ServerPid = pid()
+>
+> Open a connection to the given host.
+
+### close(ServerPid) -> ok
+
+> Types:
+>  *  ServerPid = pid()
+>
+> Brutally close the connection.
+
+### shutdown(ServerPid) -> ok
+
+> Types:
+>  *  ServerPid = pid()
+>
+> Gracefully close the connection.
+>
+> A monitor can be used to be notified when the connection is
+> effectively closed.
+
+### delete(ServerPid, Path) -> delete(ServerPid, Path, [])
+### delete(ServerPid, Path, Headers) -> StreamRef
+
+> Types:
+>  *  ServerPid = pid()
+>  *  Path = iodata()
+>  *  Headers = [{iodata(), iodata()}]
+>  *  StreamRef = reference()
+>
+> Delete a resource.
+
+### get(ServerPid, Path) -> delete(ServerPid, Path, [])
+### get(ServerPid, Path, Headers) -> StreamRef
+
+> Types:
+>  *  ServerPid = pid()
+>  *  Path = iodata()
+>  *  Headers = [{iodata(), iodata()}]
+>  *  StreamRef = reference()
+>
+> Fetch a resource.
+
+### head(ServerPid, Path) -> delete(ServerPid, Path, [])
+### head(ServerPid, Path, Headers) -> StreamRef
+
+> Types:
+>  *  ServerPid = pid()
+>  *  Path = iodata()
+>  *  Headers = [{iodata(), iodata()}]
+>  *  StreamRef = reference()
+>
+> Fetch a resource's headers.
+>
+> The server will not send the resource content, only headers.
+
+### options(ServerPid, Path) -> delete(ServerPid, Path, [])
+### options(ServerPid, Path, Headers) -> StreamRef
+
+> Types:
+>  *  ServerPid = pid()
+>  *  Path = iodata()
+>  *  Headers = [{iodata(), iodata()}]
+>  *  StreamRef = reference()
+>
+> Obtain information about the capabilities of the server or a resource.
+>
+> The special path "*" can be used to obtain information about
+> the server as a whole. Any other path will return information
+> about the resource only.
+
+### patch(ServerPid, Path, Headers) -> StreamRef
+### patch(ServerPid, Path, Headers, Body) -> StreamRef
+
+> Types:
+>  *  ServerPid = pid()
+>  *  Path = iodata()
+>  *  Headers = [{iodata(), iodata()}]
+>  *  StreamRef = reference()
+>  *  Body = iodata()
+>
+> Partially update a resource.
+>
+> Always set the content-type header so that Gun and the server
+> can be made aware that a body is going to be sent. Also try
+> to set the content-length header when possible.
+>
+> If a body is given, even an empty one, it is expected to be
+> the full resource.
+>
+> If not, Gun will assume there is no body if content-type
+> isn't set, and otherwise will expect you to stream the body.
+
+### post(ServerPid, Path, Headers) -> StreamRef
+### post(ServerPid, Path, Headers, Body) -> StreamRef
+
+> Types:
+>  *  ServerPid = pid()
+>  *  Path = iodata()
+>  *  Headers = [{iodata(), iodata()}]
+>  *  StreamRef = reference()
+>  *  Body = iodata()
+>
+> Create or update a resource.
+>
+> The resource may be created at a different URL than the one
+> given.
+>
+> Always set the content-type header so that Gun and the server
+> can be made aware that a body is going to be sent. Also try
+> to set the content-length header when possible.
+>
+> If a body is given, even an empty one, it is expected to be
+> the full resource.
+>
+> If not, Gun will assume there is no body if content-type
+> isn't set, and otherwise will expect you to stream the body.
+
+### put(ServerPid, Path, Headers) -> StreamRef
+### put(ServerPid, Path, Headers, Body) -> StreamRef
+
+> Types:
+>  *  ServerPid = pid()
+>  *  Path = iodata()
+>  *  Headers = [{iodata(), iodata()}]
+>  *  StreamRef = reference()
+>  *  Body = iodata()
+>
+> Create or update a resource.
+>
+> The resource will be created at this exact URL.
+>
+> Always set the content-type header so that Gun and the server
+> can be made aware that a body is going to be sent. Also try
+> to set the content-length header when possible.
+>
+> If a body is given, even an empty one, it is expected to be
+> the full resource.
+>
+> If not, Gun will assume there is no body if content-type
+> isn't set, and otherwise will expect you to stream the body.
+
+### request(ServerPid, Method, Path, Headers) -> StreamRef
+### request(ServerPid, Method, Path, Headers, Body) -> StreamRef
+
+> Types:
+>  *  ServerPid = pid()
+>  *  Method = iodata()
+>  *  Path = iodata()
+>  *  Headers = [{iodata(), iodata()}]
+>  *  StreamRef = reference()
+>  *  Body = iodata()
+>
+> Perform the given request on a resource.
+>
+> This is a general purpose function that should only be used
+> when no other function can be used.
+>
+> Method names are case sensitive.
+>
+> Always set the content-type header so that Gun and the server
+> can be made aware that a body is going to be sent. Also try
+> to set the content-length header when possible.
+>
+> If a body is given, even an empty one, it is expected to be
+> the full resource.
+>
+> If not, Gun will assume there is no body if content-type
+> isn't set, and otherwise will expect you to stream the body.
+
+### data(ServerPid, StreamRef, IsFin, Data) -> ok
+
+> Types:
+>  *  ServerPid = pid()
+>  *  StreamRef = reference()
+>  *  IsFin = fin | nofin
+>  *  Data = iodata()
+>
+> Stream data.
+>
+> The `StreamRef` argument is the one returned by any of the
+> request functions beforehand and uniquely identifies a request.
+>
+> Use `nofin` for all chunks except the last which should be `fin`.
+> The last chunk may be empty.
+
+### cancel(ServerPid, StreamRef) -> ok
+
+> Types:
+>  *  ServerPid = pid()
+>  *  StreamRef = reference()
+>
+> Cancel the given stream.
+>
+> The `StreamRef` argument is the one returned by any of the
+> request functions beforehand and uniquely identifies a request.
+>
+> This function will do a best effort at canceling the stream,
+> depending on the capabilities of the protocol.
+
+### ws_upgrade(ServerPid, Path) -> ws_upgrade(ServerPid, Path, [])
+### ws_upgrade(ServerPid, Path, Headers) -> ok
+
+> Types:
+>  *  ServerPid = pid()
+>  *  Path = iodata()
+>  *  Headers = [{iodata(), iodata()}]
+>
+> Upgrade the connection to Websocket.
+
+### ws_send(ServerPid, Frames) -> ok
+
+> Types:
+>  *  ServerPid = pid()
+>  *  Frames = ws_frame() | [ws_frame()]
+>
+> Send a Websocket frame.
diff --git a/manual/gun_app.md b/manual/gun_app.md
new file mode 100644
index 0000000..448145b
--- /dev/null
+++ b/manual/gun_app.md
@@ -0,0 +1,22 @@
+The Gun Application
+===================
+
+Asynchronous SPDY, HTTP and Websocket client.
+
+Dependencies
+------------
+
+The `gun` application uses the Erlang applications `ranch`
+for abstracting TCP and SSL over a common interface, and
+the applications `asn1`, `public_key` and `ssl` for using
+the SSL transport. These dependencies must be loaded for
+the `gun` application to work. In an embedded environment
+this means that they need to be started with the
+`application:start/{1,2}` function before the `gun`
+application is started.
+
+Environment
+-----------
+
+The `gun` application does not define any application
+environment configuration parameters.
diff --git a/manual/toc.md b/manual/toc.md
new file mode 100644
index 0000000..7765afc
--- /dev/null
+++ b/manual/toc.md
@@ -0,0 +1,7 @@
+Gun Function Reference
+======================
+
+The function reference documents the public interface of Gun.
+
+ *  [The Gun Application](gun_app.md)
+ *  [gun](gun.md)