Improve handler interface and documentation

This change simplifies a little more the sub protocols mechanism.
Aliases have been removed. The renaming of loop handlers as long
polling handlers has been reverted.

Plain HTTP handlers now simply do their work in the init/2
callback. There is no specific code for them.

Loop handlers now follow the same return value as Websocket,
they use ok to continue and shutdown to stop.

Terminate reasons for all handler types have been documented.
The terminate callback is now appropriately called in all cases
(or should be).

Behaviors for all handler types have been moved in the module
that implement them. This means that cowboy_handler replaces
the cowboy_http_handler behavior, and similarly cowboy_loop
replaces cowboy_loop_handler, cowboy_websocket replaces
cowboy_websocket_handler. Finally cowboy_rest now has the
start of a behavior in it and will have the full list of
optional callbacks defined once Erlang 18.0 gets released.

The guide has been reorganized and should be easier to follow.

1 files changed, 0 insertions, 50 deletions

diff --git a/doc/src/guide/multipart_intro.ezdoc b/doc/src/guide/multipart_intro.ezdoc
deleted file mode 100644
index b9a7fa9..0000000
--- a/doc/src/guide/multipart_intro.ezdoc
+++ /dev/null
@@ -1,50 +0,0 @@
-::: Introduction to multipart
-
-Multipart originates from MIME, an Internet standard that
-extends the format of emails. Multipart messages are a
-container for parts of any content-type.
-
-For example, a multipart message may have a part
-containing text and a second part containing an
-image. This is what allows you to attach files
-to emails.
-
-In the context of HTTP, multipart is most often used
-with the `multipart/form-data` content-type. This is
-the content-type you have to use when you want browsers
-to be allowed to upload files through HTML forms.
-
-Multipart is of course not required for uploading
-files, it is only required when you want to do so
-through HTML forms.
-
-:: Structure
-
-A multipart message is a list of parts. Parts may
-contain either a multipart message or a non-multipart
-content-type. This allows parts to be arranged in a
-tree structure, although this is a rare case as far
-as the Web is concerned.
-
-:: Form-data
-
-In the normal case, when a form is submitted, the
-browser will use the `application/x-www-form-urlencoded`
-content-type. This type is just a list of keys and
-values and is therefore not fit for uploading files.
-
-That's where the `multipart/form-data` content-type
-comes in. When the form is configured to use this
-content-type, the browser will use one part of the
-message for each form field. This means that a file
-input field will be sent in its own part, but the
-same applies to all other kinds of fields.
-
-A form with a text input, a file input and a select
-choice box will result in a multipart message with
-three parts, one for each field.
-
-The browser does its best to determine the content-type
-of the files it sends this way, but you should not
-rely on it for determining the contents of the file.
-Proper investigation of the contents is recommended.