Add documentation

lib/addict/controller.ex

@@ -1,9 +1,21 @@
 defmodule Addict.Controller do
+  @moduledoc """
+  The Addict Controller is used to receive User related requests directly from
+  the Phoenix router.  Adds `register/2`, `logout/2` and `login/2` functions.
+  """
   use Phoenix.Controller
   alias Addict.ManagerInteractor, as: AddictManager
 
   plug :action
 
+  @doc """
+  Entry point for registering new users.
+
+  `params` needs to include email, password and username.
+  Returns a JSON response in the format `{message: text}` with status `201` for
+  successful creation, or `400` for when an error occurs.
+  On success, it also logs the new user in.
+  """
   def register(conn, params) do
     email = params["email"]
     password = params["password"]
@@ -13,6 +25,12 @@ defmodule Addict.Controller do
     |> do_register(conn)
   end
 
+  @doc """
+  Entry point for logging out users.
+
+  Since it only deletes session data, it should always return a JSON response
+  in the format `{message: "logged out"}` with a `200` status code.
+  """
   def logout(conn, _) do
     fetch_session(conn)
     |> delete_session(:logged_in)
@@ -21,6 +39,14 @@ defmodule Addict.Controller do
     |> json %{message: "logged out"}
   end
 
+  @doc """
+  Entry point for logging users in.
+
+  Params needs to be populated with `email` and `password`. It returns `200`
+  status code along with the JSON response `{message: "logged in"}` or `400`
+  with `{message: "invalid email or password"}`
+
+  """
   def login(conn, params) do
     email = params["email"]
     password = params["password"]

lib/addict/email_gateway.ex

@@ -1,4 +1,8 @@
 defmodule Addict.EmailGateway do
+  @moduledoc """
+  The Addict EmailGateway is a wrapper for sending e-mails with the preferred
+  mail library. For now, only Mailgun is supported.
+  """
   def send_welcome_email(user, mailer \\ Addict.Mailers.Mailgun) do
     mailer.send_email_to_user "#{user.username} <#{user.email}>",
                        Application.get_env(:addict, :register_from_email),

lib/addict/mailers/mailgun.ex

@@ -1,8 +1,15 @@
 defmodule Addict.Mailers.Mailgun do
+  @moduledoc """
+  Wrapper for Mailgun client that handles eventual errors.
+  """
   require Logger
   use Mailgun.Client, domain: Application.get_env(:addict, :mailgun_domain),
                       key: Application.get_env(:addict, :mailgun_key)
 
+  @doc """
+  Sends an e-mail to a user. Returns a tuple with `{:ok, result}` on success or
+  `{:error, status_error}` on failure.
+  """
   def send_email_to_user(email, from, subject, html_body) do
     result = send_email to: email,
                  from: from,

lib/addict/manager_interactor.ex

@@ -1,12 +1,25 @@
 defmodule Addict.ManagerInteractor do
+  @moduledoc """
+  Addict Manager Interactor responsability is to provide simple primtives for
+  user operations.
+  """
   require Logger
 
+
+  @doc """
+  Creates a user on the database and sends the welcoming e-mail via the defined
+  `mailer`.
+  """
   def create(email, username, password, repo \\ Addict.Repository, mailer \\ Addict.EmailGateway) do
     generate_password(password)
     |> create_username(email, username, repo)
     |> send_welcome_email(mailer)
   end
 
+  @doc """
+  Verifies if the provided `password` is the same as the `password` for the user
+  associated with the given `email`.
+  """
   def verify_password(email, password, repo \\ Addict.Repository) do
     user = repo.find_by_email email
 

lib/addict/plugs/authenticated.ex

@@ -1,11 +1,26 @@
 defmodule Addict.Plugs.Authenticated do
+  @moduledoc """
+  Authenticated plug can be used to filter actions for users that are
+  authenticated.
+  """
   import Plug.Conn
   use Phoenix.Controller
 
   def init(options) do
     options
   end
 
+
+  @doc """
+  Call represents the use of the plug itself.
+
+  When called, it will populate `conn` with the `current_user`, so it is
+  possible to always retrieve the user via `conn[:current_user]`.
+
+  In case the user is not logged in, it will redirect the request to
+  the Application :addict :not_logged_in_url page. If none is defined, it will
+  redirect to `/error`.
+  """
   def call(conn, _) do
     fetch_session(conn)
 

lib/addict/repository.ex

@@ -1,10 +1,21 @@
 defmodule Addict.Repository do
+  @moduledoc """
+  Addict Repository is responsible for interacting with the DB on the query
+  level in order to manipulate user data.
+  """
   require Logger
 
   import Ecto.Query
+
   @user Application.get_env(:addict, :user)
   @db Application.get_env(:addict, :db)
 
+  @doc """
+  Creates a new user on the database with the given parameters.
+
+  It either returns a tuple with `{:ok, user}` or, in case an error
+  happens, a tuple with `{:error, error_message}`
+  """
   def create(salt, hash, email, username) do
     try do
       new_user = @db.insert(struct(@user,%{
@@ -22,6 +33,12 @@ defmodule Addict.Repository do
     end
   end
 
+  @doc """
+  Retrieves a single user from the database based on the user's e-mail.
+
+  It either returns the `user` or, in case an error occurs, a tuple with
+  `{:error, error_message}`. If no user exists, `nil` will be returned.
+  """
   def find_by_email(email) do
     try do
       query = from u in @user, where: u.email == ^email