expand documentation

Author: slogsdon

README.md

@@ -1,5 +1,133 @@
 # HttpRouter
+[![Build Status](https://img.shields.io/travis/slogsdon/elixir-http-router.svg?style=flat)](https://travis-ci.org/slogsdon/elixir-http-router)
+[![Coverage Status](https://img.shields.io/coveralls/slogsdon/elixir-http-router.svg?style=flat)](https://coveralls.io/r/slogsdon/elixir-http-router)
+[![Hex.pm Version](http://img.shields.io/hexpm/v/http_router.svg?style=flat)](https://hex.pm/packages/http_router)
 
-HTTP Router with various macros to assist in
-developing your application and organizing
-your code
+> HTTP Router with various macros to assist in
+> developing your application and organizing
+> your code
+
+## Installation
+
+Add the following line to your dependency list
+in your `mix.exs` file, and run `mix deps.get`:
+
+```elixir
+{:http_router, "~> 0.0.1"}
+```
+
+Also, be sure to add `:http_router` to the list
+of applications on which your web application
+depends (the default looks something like
+`applications: [:logger]`) in your `mix.exs`
+file.
+
+Be sure to have [Plug][plug] in your dependency
+list as well as this is essentially a
+reimagination of the `Plug.Router` module, and
+as such, it still make use of a large portion
+of the Plug library.
+
+## Usage
+
+To get the benefits that this package has to
+offer, it is necessary to use the `HttpRouter`
+module in one of your modules that you wish to
+act as the router for your web application.
+Similar to `Plug.Router`, we can start with a
+simple module:
+
+```elixir
+defmodule MyRouter do
+  use HttpRouter
+end
+```
+
+That was easy, huh? Now, this module still needs a
+few calls to the below macros, but this depends on
+how your application needs to be structured.
+
+### The Macros
+
+Check out this convoluted example:
+
+```elixir
+defmodule MyRouter do
+  use HttpRouter
+
+  # Define one of the versions of the API
+  # with a simple version number "1"
+  # or following semver "1.0.0"
+  # or date of release "2014-09-06"
+  version "1" do
+    # Define your routes here
+    get  "/",               Handlers.V1.Pages, :index
+    get  "/pages",          Handlers.V1.Pages, :create
+    post "/pages",          Handlers.V1.Pages, :create
+    put  "/pages/:page_id" when id == 1,
+                            Handlers.V1.Pages, :update_only_one
+    get  "/pages/:page_id", Handlers.V1.Pages, :show
+
+    # Auto-create a full set of routes for resources
+    #
+    resource :users,        Handlers.V1.User, arg: :user_id
+    #
+    # Generates:
+    #
+    # get     "/users",           Handlers.V1.User, :index
+    # post    "/users",           Handlers.V1.User, :create
+    # get     "/users/:user_id",  Handlers.V1.User, :show
+    # put     "/users/:user_id",  Handlers.V1.User, :update
+    # patch   "/users/:user_id",  Handlers.V1.User, :patch
+    # delete  "/users/:user_id",  Handlers.V1.User, :delete
+    #
+    # options "/users",           "HEAD,GET,POST"
+    # options "/users/:_user_id", "HEAD,GET,PUT,PATCH,DELETE"
+  end
+
+  # An updated version of the AP
+  version "2" do
+    get  "/",               Handlers.V2.Pages,  :index
+    post "/pages",          Handlers.V2.Pages,  :create
+    get  "/pages/:page_id", Handlers.V2.Pages,  :show
+    put  "/pages/:page_id", Handlers.V2.Pages,  :update
+
+    raw :trace, "/trace",   Handlers.V2.Tracer, :trace
+
+    resource :users,        Handlers.V2.User
+    resource :groups,       Handlers.V2.Group
+  end
+end
+```
+
+`get/3`, `post/3`, `put/3`, `patch/3`, `delete/3`,
+`options/2`, and `any/3` are already built-in as
+described. `resource` exists but will need
+modifications to create everything as noted.
+
+`raw/4` allows for using custom HTTP methods, allowing
+your application to be HTTP spec compliant.
+
+`version/2` will need to be created outright. Will
+allow requests to contained endpoints when version
+exists in either `Accepts` header or URL (which ever
+is defined in app config).
+
+Extra routes will need to be added for `*.json`,
+`*.xml`, etc. requests for optionally specifying
+desired content type without the use of the
+`Accepts` header. These should match
+parsing/rendering abilities of your application.
+
+## Configuration
+
+TBD.
+
+## License
+
+HttpRouter is released under the MIT License.
+
+See [LICENSE](license) for details.
+
+[plug]: https://github.com/elixir-lang/plug
+[license]: https://github.com/slogsdon/elixir-http-router/blob/master/LICENSE