Merge pull request #40 from inaka/flavio.fix.dayron-main-doc

dayron main doc

CHANGELOG.md

@@ -1,5 +1,5 @@
 # Changelog
 
-## v0.1.0 (2016-05-04)
+## v0.1.0 (2016-05-20)
 
 * Initial release

README.md

@@ -5,7 +5,7 @@
 [![Coverage Status](https://coveralls.io/repos/github/inaka/Dayron/badge.svg?branch=master)](https://coveralls.io/github/inaka/Dayron?branch=master)
 [![Twitter](https://img.shields.io/badge/twitter-@inaka-blue.svg?style=flat)](http://twitter.com/inaka)
 
-Dayron is a flexible library to interact with resources from REST APIs and map them to models in Elixir. It works _similar_ of [Ecto.Repo](https://github.com/elixir-lang/ecto) but, instead of retrieving data from a database, it has underlying http clients to retrieve data from external HTTP servers.
+Dayron is a flexible library to interact with resources from REST APIs and map them to data structures in Elixir. It works _similar_ of [Ecto.Repo](https://github.com/elixir-lang/ecto) but, instead of retrieving data from a database, it has underlying http clients to retrieve data from external HTTP servers.
 
 ## Installation
 

lib/dayron.ex

@@ -1,5 +1,102 @@
 defmodule Dayron do
-  @moduledoc false
+  @moduledoc ~S"""
+  Dayron is split into 2 main components:
+
+    * `Dayron.Repo` - repositories are wrappers around HTTP clients.
+      Via the repository, we can send requests to external REST APIs,
+      performing actions to get, create, update or destroy resources.
+      A repository needs an adapter and the api URL. HTTPoison is the default
+      built-in adapter.
+
+    * `Dayron.Model` - models allow developers to define structures
+      that map the external resources into local data. It also implements
+      callbacks to handle specific configuration, such as the resource name
+      used by the request and the data mapping rules.
+
+  In the following sections, we will provide an overview of those components
+  and how they interact with each other. Feel free to access their respective
+  module documentation for more specific examples, options and configuration.
+
+  If you want to quickly check a sample application using Dayron, please check
+  https://github.com/inaka/dayron/tree/master/examples/simple_blog.
+
+  ## Repositories
+
+  `Dayron.Repo` is a wrapper around a rest client. We can define a
+  repository as follows:
+
+      defmodule RestRepo do
+        use Dayron.Repo, otp_app: :my_app
+      end
+
+  Where the configuration for the Repo must be in your application
+  environment, usually defined in your `config/config.exs`:
+
+      config :my_app, MyApp.RestRepo,
+        url: "https://api.example.com",
+        headers: [access_token: "token"]
+
+  ## Model
+
+  A Model provides a set of functionalities around mapping the external data
+  into local structures.
+
+  Let's see an User model example:
+
+      defmodule User do
+        use Dayron.Model, resource: "users"
+
+        defstruct id: nil, name: "", age: 0
+      end
+
+  The model allows us to interact with the REST API using our repository:
+
+      # Inserting a new user
+      iex> user = %User{name: "User Name", age: 23}
+      iex> RestRepo.insert!(User, user)
+      {:ok, %User{...}}
+
+      # Get the resource data back
+      iex> user = RestRepo.get User, "user-id"
+      %User{id: "user-id", ...}
+
+      # Delete it
+      iex> RestRepo.delete!(User, "user-id")
+      {:ok, %User{...}}
+
+  As an example, let's see how we could use the User Model above in
+  a web application that needs to update users:
+
+      def update(id, %{"user" => user_params}) do
+        case RestRepo.update(User, id, user_params) do
+          {:ok, user} ->
+            send_resp conn, 200, "Ok"
+          {:error, error} ->
+            send_resp conn, 400, "Bad request"
+        end
+      end
+
+  The Repo methods also accepts extra options. If you want to send a list of
+  parameters to be sent in the query when retrieving a list of users, for
+  example:
+
+      iex> RestRepo.all(User, params: [name: "a user name"])
+      [%User{...}, %User{...}]
+
+  If you check the application logs, you'll see the complete request/response
+  information:
+
+      [debug] GET https://api.example.com/users
+      Options:
+        Params: name="a user name"
+      Body: -
+      Headers:
+        access_token: "token"
+      [debug] Response: 200 in 718ms
+
+  For a complete list of avaliable options, please check `Dayron.Adapter`
+  module.
+  """
   use Application
   alias Mix.Project
 

lib/dayron/model.ex

@@ -2,10 +2,29 @@ defmodule Dayron.Model do
   @moduledoc """
   Defines the functions to convert a module into a Dayron Model.
 
-  Given an module with Ecto.Schema included, the macro will include everything
-  required for Dayron.Repo and Dayron.Client to get and send data to the
-  external Rest Api. The Schema definition is required to convert the api
-  response json to a valid struct, mapping the json attributes to fields.
+  A Model provides a set of functionalities around mapping the external data
+  into local structures.
+
+  In order to convert an Elixir module into a Model, Dayron provides a
+  `Dayron.Model` mixin, that requires a `resource` option and a struct
+  defining the available fields.
+
+  ## Example
+
+      defmodule User do
+        use Dayron.Model, resource: "users"
+
+        defstruct name: "", age: 0
+      end
+
+  The `resource` option value defines the complete API URL when requesting
+  this model. For the above example, api calls will be made to
+  http://YOUR_API_URL/users.
+
+  Given an module with Ecto.Schema already included, the `Dayron.Model` mixin
+  will include everything required for Dayron.Repo to get and send data to the
+  external Rest Api. The `schema` will be used to map external api responses
+  data to local structs.
 
   ## Example
 
@@ -19,9 +38,9 @@ defmodule Dayron.Model do
         end
       end
 
-  By default the resource name is defined based on the schema source name, in
-  the above example "users", to api calls will be made to http://YOUR_API_URL/
-  users. In order to replace this, a :resource option is available.
+  In that case, resource name is defined based on the schema source name, or
+  "users" in the above example. To replace the value, inform a `resource`
+  option when including the mixin.
 
   ## Example
 
@@ -37,6 +56,17 @@ defmodule Dayron.Model do
 
   If some pre-processing is required to convert the json data into the struct,
   it's possible to override __from_json__/2 into the module.
+
+  ## Example
+
+      def __from_json__(data, _options) do
+        updated_data =
+          data
+          |> Map.get(:details)
+          |> Map.delete(:type)
+        struct(__MODULE__, updated_data)
+      end
+
   """
   alias Dayron.Requestable