Convert the documentation to Asciidoc

A few small revisions were made, and Erlang.mk has been updated.

1 files changed, 0 insertions, 536 deletions

diff --git a/doc/src/manual/cowboy_rest.ezdoc b/doc/src/manual/cowboy_rest.ezdoc
deleted file mode 100644
index 35131c7..0000000
--- a/doc/src/manual/cowboy_rest.ezdoc
+++ /dev/null
@@ -1,536 +0,0 @@
-::: cowboy_rest
-
-The `cowboy_rest` module implements REST semantics on top of
-the HTTP protocol.
-
-This module is a sub protocol that defines many callbacks
-be implemented by handlers. The `init/2` and `terminate/3`
-callbacks are common to all handler types and are documented
-in the manual for the ^cowboy_handler module.
-
-All other callbacks are optional, though some may become
-required depending on the return value of previous callbacks.
-
-:: Meta values
-
-: charset
-
-Type: binary()
-
-Negotiated charset.
-
-This value may not be defined if no charset was negotiated.
-
-: language
-
-Type: binary()
-
-Negotiated language.
-
-This value may not be defined if no language was negotiated.
-
-: media_type
-
-Type: {binary(), binary(), '*' | [{binary(), binary()}]}
-
-Negotiated media-type.
-
-The media-type is the content-type, excluding the charset.
-
-This value is always defined after the call to
-`content_types_provided/2`.
-
-:: Terminate reasons
-
-The following values may be received as the terminate reason
-in the optional `terminate/3` callback.
-
-: normal
-
-The connection was closed normally.
-
-: {crash, Class, Reason}
-
-A crash occurred in the handler. `Class` and `Reason` can be
-used to obtain more information about the crash. The function
-`erlang:get_stacktrace/0` can also be called to obtain the
-stacktrace of the process when the crash occurred.
-
-:: Callbacks
-
-: Callback(Req, State) -> {Value, Req, State} | {stop, Req, State}
-
-Types:
-
-* Callback - one of the REST callbacks described below
-* Req = cowboy_req:req()
-* State = any()
-* Value - see the REST callbacks description below
-
-Please see the REST callbacks description below for details
-on the `Value` type, the default value if the callback is
-not defined, and more general information on when the
-callback is called and what its intended use is.
-
-The `stop` tuple can be returned to stop REST processing.
-It is up to the resource code to send a reply before that,
-otherwise a `204 No Content` will be sent.
-
-:: REST callbacks description
-
-: allowed_methods
-
-* Methods: all
-* Value type: [binary()]
-* Default value: [<<"GET">>, <<"HEAD">>, <<"OPTIONS">>]
-
-Return the list of allowed methods.
-
-Methods are case sensitive. Standard methods are always uppercase.
-
-: allow_missing_post
-
-* Methods: POST
-* Value type: boolean()
-* Default value: true
-
-Return whether POST is allowed when the resource doesn't exist.
-
-Returning `true` here means that a new resource will be
-created. The URL to the created resource should also be
-returned from the `AcceptResource` callback.
-
-: charsets_provided
-
-* Methods: GET, HEAD, POST, PUT, PATCH, DELETE
-* Value type: [binary()]
-* Skip to the next step if undefined
-
-Return the list of charsets the resource provides.
-
-The list must be ordered in order of preference.
-
-If the accept-charset header was not sent, the first charset
-in the list will be selected. Otherwise Cowboy will select
-the most appropriate charset from the list.
-
-The chosen charset will be set in the `Req` object as the meta
-value `charset`.
-
-While charsets are case insensitive, this callback is expected
-to return them as lowercase binary.
-
-: content_types_accepted
-
-* Methods: POST, PUT, PATCH
-* No default
-
-Types:
-
-* Value = [{binary() | {Type, SubType, Params}, AcceptResource}]
-* Type = SubType = binary()
-* Params = '*' | [{binary(), binary()}]
-* AcceptResource = atom()
-
-Return the list of content-types the resource accepts.
-
-The list must be ordered in order of preference.
-
-Each content-type can be given either as a binary string or as
-a tuple containing the type, subtype and parameters.
-
-Cowboy will select the most appropriate content-type from the list.
-If any parameter is acceptable, then the tuple form should be used
-with parameters set to `'*'`. If the parameters value is set to `[]`
-only content-type values with no parameters will be accepted. All
-parameter values are treated in a case sensitive manner except the
-`charset` parameter, if present, which is case insensitive.
-
-This function will be called for POST, PUT and PATCH requests.
-It is entirely possible to define different callbacks for different
-methods if the handling of the request differs. Simply verify
-what the method is with `cowboy_req:method/1` and return a
-different list for each methods.
-
-The `AcceptResource` value is the name of the callback that will
-be called if the content-type matches. It is defined as follow.
-
-* Value type: true | {true, URL} | false
-* No default
-
-Process the request body.
-
-This function should create or update the resource with the
-information contained in the request body. This information
-may be full or partial depending on the request method.
-
-If the request body was processed successfully, `true` must
-be returned. If the request method is POST, `{true, URL}` may
-be returned instead, and Cowboy will redirect the client to
-the location of the newly created resource.
-
-If a response body must be sent, the appropriate media-type, charset
-and language can be retrieved using the `cowboy_req:meta/{2,3}`
-functions. The respective keys are `media_type`, `charset`
-and `language`. The body can be set using `cowboy_req:set_resp_body/2`.
-
-: content_types_provided
-
-* Methods: GET, HEAD, POST, PUT, PATCH, DELETE
-* Default value: [{{<<"text">>, <<"html">>, '*'}, to_html}]
-
-Types:
-
-* Value = [{binary() | {Type, SubType, Params}, ProvideResource}]
-* Type = SubType = binary()
-* Params = '*' | [{binary(), binary()}]
-* ProvideResource = atom()
-
-Return the list of content-types the resource provides.
-
-The list must be ordered in order of preference.
-
-Each content-type can be given either as a binary string or as
-a tuple containing the type, subtype and parameters.
-
-Cowboy will select the most appropriate content-type from the list.
-If any parameter is acceptable, then the tuple form should be used
-with parameters set to `'*'`. If the parameters value is set to `[]`
-only content-type values with no parameters will be accepted. All
-parameter values are treated in a case sensitive manner except the
-`charset` parameter, if present, which is case insensitive.
-
-The `ProvideResource` value is the name of the callback that will
-be called if the content-type matches. It will only be called when
-a representation of the resource needs to be returned. It is defined
-as follow.
-
-* Methods: GET, HEAD
-* Value type: iodata() | {stream, Fun} | {stream, Len, Fun} | {chunked, ChunkedFun}
-* No default
-
-Return the response body.
-
-The response body may be provided directly or through a fun.
-If a fun tuple is returned, the appropriate `set_resp_body_fun`
-function will be called. Please refer to the documentation for
-these functions for more information about the types.
-
-The call to this callback happens a good time after the call to
-`content_types_provided/2`, when it is time to start rendering
-the response body.
-
-: delete_completed
-
-* Methods: DELETE
-* Value type: boolean()
-* Default value: true
-
-Return whether the delete action has been completed.
-
-This function should return `false` if there is no guarantee
-that the resource gets deleted immediately from the system,
-including from any internal cache.
-
-When this function returns `false`, a `202 Accepted`
-response will be sent instead of a `200 OK` or `204 No Content`.
-
-: delete_resource
-
-* Methods: DELETE
-* Value type: boolean()
-* Default value: false
-
-Delete the resource.
-
-The value returned indicates if the action was successful,
-regardless of whether the resource is immediately deleted
-from the system.
-
-: expires
-
-* Methods: GET, HEAD
-* Value type: calendar:datetime() | binary() | undefined
-* Default value: undefined
-
-Return the date of expiration of the resource.
-
-This date will be sent as the value of the expires header.
-
-: forbidden
-
-* Methods: all
-* Value type: boolean()
-* Default value: false
-
-Return whether access to the resource is forbidden.
-
-A `403 Forbidden` response will be sent if this
-function returns `true`. This status code means that
-access is forbidden regardless of authentication,
-and that the request shouldn't be repeated.
-
-: generate_etag
-
-* Methods: GET, HEAD, POST, PUT, PATCH, DELETE
-* Value type: binary() | {weak | strong, binary()}
-* Default value: undefined
-
-Return the entity tag of the resource.
-
-This value will be sent as the value of the etag header.
-
-If a binary is returned, then the value will be parsed
-to the tuple form automatically. The value must be in
-the same format as the etag header, including quotes.
-
-: is_authorized
-
-* Methods: all
-* Value type: true | {false, AuthHeader}
-* Default value: true
-
-Types:
-
-* AuthHead = iodata()
-
-Return whether the user is authorized to perform the action.
-
-This function should be used to perform any necessary
-authentication of the user before attempting to perform
-any action on the resource.
-
-If the authentication fails, the value returned will be sent
-as the value for the www-authenticate header in the
-`401 Unauthorized` response.
-
-: is_conflict
-
-* Methods: PUT
-* Value type: boolean()
-* Default value: false
-
-Return whether the put action results in a conflict.
-
-A `409 Conflict` response will be sent if this function
-returns `true`.
-
-: known_methods
-
-* Methods: all
-* Value type: [binary()]
-* Default value: [<<"GET">>, <<"HEAD">>, <<"POST">>, <<"PUT">>, <<"PATCH">>, <<"DELETE">>, <<"OPTIONS">>]
-
-Return the list of known methods.
-
-The full list of methods known by the server should be
-returned, regardless of their use in the resource.
-
-The default value lists the methods Cowboy knows and
-implement in `cowboy_rest`.
-
-Methods are case sensitive. Standard methods are always uppercase.
-
-: languages_provided
-
-* Methods: GET, HEAD, POST, PUT, PATCH, DELETE
-* Value type: [binary()]
-* Skip to the next step if undefined
-
-Return the list of languages the resource provides.
-
-The list must be ordered in order of preference.
-
-If the accept-language header was not sent, the first language
-in the list will be selected. Otherwise Cowboy will select
-the most appropriate language from the list.
-
-The chosen language will be set in the `Req` object as the meta
-value `language`.
-
-While languages are case insensitive, this callback is expected
-to return them as lowercase binary.
-
-: last_modified
-
-* Methods: GET, HEAD, POST, PUT, PATCH, DELETE
-* Value type: calendar:datetime()
-* Default value: undefined
-
-Return the date of last modification of the resource.
-
-This date will be used to test against the if-modified-since
-and if-unmodified-since headers, and sent as the last-modified
-header in the response of GET and HEAD requests.
-
-: malformed_request
-
-* Methods: all
-* Value type: boolean()
-* Default value: false
-
-Return whether the request is malformed.
-
-Cowboy has already performed all the necessary checks
-by the time this function is called, so few resources
-are expected to implement it.
-
-The check is to be done on the request itself, not on
-the request body, which is processed later.
-
-: moved_permanently
-
-* Methods: GET, HEAD, POST, PUT, PATCH, DELETE
-* Value type: {true, URL} | false
-* Default value: false
-
-Types:
-
-* URL = iodata()
-
-Return whether the resource was permanently moved.
-
-If it was, its new URL is also returned and sent in the
-location header in the response.
-
-: moved_temporarily
-
-* Methods: GET, HEAD, POST, PATCH, DELETE
-* Value type: {true, URL} | false
-* Default value: false
-
-Types:
-
-* URL = iodata()
-
-Return whether the resource was temporarily moved.
-
-If it was, its new URL is also returned and sent in the
-location header in the response.
-
-: multiple_choices
-
-* Methods: GET, HEAD, POST, PUT, PATCH, DELETE
-* Value type: boolean()
-* Default value: false
-
-Return whether there are multiple representations of the resource.
-
-This function should be used to inform the client if there
-are different representations of the resource, for example
-different content-type. If this function returns `true`,
-the response body should include information about these
-different representations using `cowboy_req:set_resp_body/2`.
-The content-type of the response should be the one previously
-negociated and that can be obtained by calling
-`cowboy_req:meta(media_type, Req)`.
-
-: options
-
-* Methods: OPTIONS
-* Value type: ok
-* Default value: ok
-
-Handle a request for information.
-
-The response should inform the client the communication
-options available for this resource.
-
-By default, Cowboy will send a `200 OK` response with the
-allow header set.
-
-: previously_existed
-
-* Methods: GET, HEAD, POST, PATCH, DELETE
-* Value type: boolean()
-* Default value: false
-
-Return whether the resource existed previously.
-
-: resource_exists
-
-* Methods: GET, HEAD, POST, PUT, PATCH, DELETE
-* Value type: boolean()
-* Default value: true
-
-Return whether the resource exists.
-
-If it exists, conditional headers will be tested before
-attempting to perform the action. Otherwise, Cowboy will
-check if the resource previously existed first.
-
-: service_available
-
-* Methods: all
-* Value type: boolean()
-* Default value: true
-
-Return whether the service is available.
-
-This function can be used to test that all relevant backend
-systems are up and able to handle requests.
-
-A `503 Service Unavailable` response will be sent if this
-function returns `false`.
-
-: uri_too_long
-
-* Methods: all
-* Value type: boolean()
-* Default value: false
-
-Return whether the requested URI is too long.
-
-Cowboy has already performed all the necessary checks
-by the time this function is called, so few resources
-are expected to implement it.
-
-A `414 Request-URI Too Long` response will be sent if this
-function returns `true`.
-
-: valid_content_headers
-
-* Methods: all
-* Value type: boolean()
-* Default value: true
-
-Return whether the content-* headers are valid.
-
-This also applies to the transfer-encoding header. This
-function must return `false` for any unknown content-*
-headers, or if the headers can't be understood. The
-function `cowboy_req:parse_header/2` can be used to
-quickly check the headers can be parsed.
-
-A `501 Not Implemented` response will be sent if this
-function returns `false`.
-
-: valid_entity_length
-
-* Methods: all
-* Value type: boolean()
-* Default value: true
-
-Return whether the request body length is within acceptable boundaries.
-
-A `413 Request Entity Too Large` response will be sent if this
-function returns `false`.
-
-: variances
-
-* Methods: GET, HEAD, POST, PUT, PATCH, DELETE
-* Value type: [binary()]
-* Default value: []
-
-Return the list of headers that affect the representation of the resource.
-
-These request headers return the same resource but with different
-parameters, like another language or a different content-type.
-
-Cowboy will automatically add the accept, accept-language and
-accept-charset headers to the list if the respective functions
-were defined in the resource.
-
-This operation is performed right before the `resource_exists/2`
-callback. All responses past that point will contain the vary
-header which holds this list.