Merge pull request #36 from ateliware/better-docs

Better docs

README.md

@@ -2,7 +2,7 @@
 
 [![Build Status](https://travis-ci.org/ateliware/triplex.svg?branch=master)](https://travis-ci.org/ateliware/triplex)
 [![Hex pm](http://img.shields.io/hexpm/v/triplex.svg?style=flat)](https://hex.pm/packages/triplex)
-[![Coverage Status](https://coveralls.io/repos/github/ateliware/triplex/badge.svg)](https://coveralls.io/github/ateliware/triplex)
+[![Coverage Status](https://coveralls.io/repos/github/ateliware/triplex/badge.svg?branch=master)](https://coveralls.io/github/ateliware/triplex?branch=master)
 [![Code Climate](https://img.shields.io/codeclimate/github/ateliware/triplex.svg)](https://codeclimate.com/github/ateliware/triplex)
 [![Inline docs](http://inch-ci.org/github/ateliware/triplex.svg?branch=master&style=flat)](http://inch-ci.org/github/ateliware/triplex)
 
@@ -64,6 +64,8 @@ And if you're sick of it and want to drop:
 Triplex.drop("my_tenant")
 ```
 
+More information on `Triplex` module documentation.
+
 ### Creating tables inside tenant
 
 To create a table inside your tenant you can use:
@@ -88,6 +90,9 @@ This task will migrate all your existent tenants, one by one. If it
 fail in any tenant, the next time you run it will continue from where
 it stoped.
 
+If you need more information, check the `Mix.Triplex` documentation, where
+you can find the list of tasks and their descriptions.
+
 ### Querying, updating and inserting data inside tenants
 
 To make queries, updates and inserts inside your tenant is quite easy.
@@ -101,3 +106,15 @@ Repo.all(User, prefix: Triplex.to_prefix("my_tenant"))
 It's a good idea to call `Triplex.to_prefix/1` on your tenant name, altough is
 not required. Because, if you configured a `tenant_prefix`, this function will
 return the prefixed one.
+
+### Loading the current tenant to your `Plug.Conn`
+
+We have some basic and configurable plugs you can use to load the current
+tenant on your web app. Here is an example loading it from the subdomain:
+
+```elixir
+plug Triplex.SubdomainPlug, endpoint: MyApp.Endpoint
+```
+
+For more information, check the `Triplex.Plug` documentation for an overview of
+our plugs.

lib/mix/tasks/triplex.rollback.ex

@@ -12,26 +12,36 @@ defmodule Mix.Tasks.Triplex.Rollback do
 
   @moduledoc """
   Reverts applied migrations in the given repository.
+
   The repository must be set under `:ecto_repos` in the
   current app configuration or given via the `-r` option.
+
   By default, migrations are expected at "priv/YOUR_REPO/migrations"
   directory of the current application but it can be configured
   by specifying the `:priv` key under the repository configuration.
+
   Runs the latest applied migration by default. To roll back to
   to a version number, supply `--to version_number`.
+
   To roll back a specific number of times, use `--step n`.
+
   To undo all applied migrations, provide `--all`.
+
   If the repository has not been started yet, one will be
   started outside our application supervision tree and shutdown
   afterwards.
+
   ## Examples
+
       mix ecto.rollback
       mix ecto.rollback -r Custom.Repo
       mix ecto.rollback -n 3
       mix ecto.rollback --step 3
       mix ecto.rollback -v 20080906120000
       mix ecto.rollback --to 20080906120000
+
   ## Command line options
+
     * `-r`, `--repo` - the repo to rollback
     * `--all` - revert all applied migrations
     * `--step` / `-n` - revert n number of applied migrations

lib/mix/triplex.ex

@@ -1,10 +1,26 @@
 defmodule Mix.Triplex do
   @moduledoc """
   Useful functions for any triplex mix task.
+
+  Here is the list of tasks we have for now:
+
+  - [`mix triplex.gen.migration`](./Mix.Tasks.Triplex.Gen.Migration.html) -
+  generates a tenant migration for the repo
+  - [`mix triplex.migrate`](./Mix.Tasks.Triplex.Migrate.html) -
+  runs the repository tenant migrations
+  - [`mix triplex.migrations`](./Mix.Tasks.Triplex.Migrations.html) -
+  displays the repository migration status
+  - [`mix triplex.rollback`](./Mix.Tasks.Triplex.Rollback.html) -
+  rolls back the repository tenant migrations
   """
 
   alias Mix.Project
 
+  @doc """
+  Ensures the migrations path exists for the given repo.
+
+  Raises a `Mix.raise` if it fails and returns the repo if succeed.
+  """
   def ensure_tenant_migrations_path(repo, config \\ Project.config()) do
     with false <- Project.umbrella?(config),
          path = relative_migrations_path(repo, config),

lib/triplex.ex

@@ -25,6 +25,10 @@ defmodule Triplex do
   alias Ecto.Migrator
   alias Postgrex.Error, as: PGError
 
+  @doc """
+  Returns a `%Triplex.Config{}` struct with all the args loaded from the app
+  configuration.
+  """
   def config, do: struct(Triplex.Config, Application.get_all_env(:triplex))
 
   @doc """
@@ -50,8 +54,8 @@ defmodule Triplex do
 
   The function `to_prefix/1` will be applied to the tenant.
   """
-  def reserved_tenant?(map) when is_map(map) do
-    map
+  def reserved_tenant?(tenant) when is_map(tenant) do
+    tenant
     |> tenant_field()
     |> reserved_tenant?()
   end
@@ -107,9 +111,6 @@ defmodule Triplex do
   @doc """
   Renames the given tenant on the given repo.
 
-  If any given tenant is a map, it will apply `tenant_field/1` to it and get
-  the prefix from the field.
-
   If the repo is not given, it uses the one you configured.
   """
   def rename(old_tenant, new_tenant, repo \\ config().repo) do
@@ -170,11 +171,11 @@ defmodule Triplex do
   end
 
   @doc """
-  Migrates the given tenant.
+  Migrates the given tenant on your repo.
 
   The function `to_prefix/1` will be applied to the tenant.
 
-  If the repo is not given, it uses the one you configured.
+  If the `repo` is not given, it uses the one you configured.
   """
   def migrate(tenant, repo \\ config().repo) do
     Code.compiler_options(ignore_module_conflict: true)
@@ -193,7 +194,7 @@ defmodule Triplex do
   @doc """
   Return the path for your tenant migrations.
 
-  If the repo is not given, it uses the one you configured.
+  If the `repo` is not given, it uses the one you configured.
   """
   def migrations_path(repo \\ config().repo) do
     if repo do
@@ -240,8 +241,8 @@ defmodule Triplex do
   will get the `tenant_field/0` from it to concat the prefix.
   """
   def to_prefix(tenant, prefix \\ config().tenant_prefix)
-  def to_prefix(map, prefix) when is_map(map) do
-    map
+  def to_prefix(tenant, prefix) when is_map(tenant) do
+    tenant
     |> tenant_field()
     |> to_prefix(prefix)
   end

lib/triplex/ensure_plug.ex

@@ -8,7 +8,7 @@ defmodule Triplex.EnsurePlug do
         callback: &TenantHelper.callback/2
         failure_callback: &TenantHelper.failure_callback/2
 
-  See `Triplex.PlugConfig` to check all the allowed configuration flags.
+  See `Triplex.PlugConfig` to check all the allowed `config` flags.
   """
 
   import Triplex.Plug

lib/triplex/param_plug.ex

@@ -9,7 +9,7 @@ defmodule Triplex.ParamPlug do
         param: :subdomain,
         tenant_handler: &TenantHelper.tenant_handler/1
 
-  See `Triplex.PlugConfig` to check all the allowed configuration flags.
+  See `Triplex.PlugConfig` to check all the allowed `config` flags.
   """
 
   import Triplex.Plug

lib/triplex/plug.ex

@@ -1,6 +1,16 @@
 defmodule Triplex.Plug do
   @moduledoc """
   This module have some basic functions for our triplex plugs.
+
+  The plugs we have for now are:
+
+  - `Triplex.ParamPlug` - loads the tenant from a body or query param
+  - `Triplex.SessionPlug` - loads the tenant from a session param
+  - `Triplex.SubdomainPlug` - loads the tenant from the url subdomain
+  - `Triplex.EnsurePlug` - ensures the current tenant is loaded and halts if not
+
+  You can also check `Triplex.PlugConfig` for the config options you have for
+  each plug.
   """
 
   import Plug.Conn
@@ -11,7 +21,7 @@ defmodule Triplex.Plug do
   Puts the given tenant as an assign on the given conn, but only if the
   tenant is not reserved.
 
-  See `Triplex.PlugConfig` to the allowed configuration flags.
+  See `Triplex.PlugConfig` to the allowed `config` flags.
   """
   def put_tenant(conn, tenant, config) do
     if conn.assigns[config.assign] do
@@ -28,9 +38,9 @@ defmodule Triplex.Plug do
   end
 
   @doc """
-  Ensure the tenant is loaded, and if not, halts the conn.
+  Ensure the tenant is loaded, and if not, halts the `conn`.
 
-  See `Triplex.PlugConfig` to the allowed configuration flags.
+  See `Triplex.PlugConfig` to the allowed `config` flags.
   """
   def ensure_tenant(conn, config) do
     if loaded_tenant = conn.assigns[config.assign] do

lib/triplex/plug_config.ex

@@ -1,34 +1,25 @@
 defmodule Triplex.PlugConfig do
   @moduledoc """
-  This is a struct that holds basic configuration for triplex plugs.
+  This is a struct that holds all the configuration for triplex plugs.
 
   Here are the config keys we have:
 
-  ## For all plugs
-
-  - `tenant_handler`: function to handle te test param. The return of it will
-  be used as the tenant.
-  - `assign`: the name of the assign where we must save the tenant.
-
-  ## For `Triplex.EnsurePlug`
-
-  - `callback`: function that might be called when the plug succeeded. It
-  must return a connection.
-  - `failure_callback`: function that might be called when the plug failed.
-  It must return a connection.
-
-  ## For `Triplex.ParamPlug`
-
-  - `param`: the param name to load the tenant from.
-
-  ## For `Triplex.SessionPlug`
-
-  - `session`: the session param name to load the tenant from.
-
-  ## For `Triplex.SubdomainPlug`
-
-  - `endpoint`: the Phoenix.Endpoint to get the host name to dicover the
-  subdomain.
+  - For all plugs
+    - `tenant_handler`: function to handle te test param. The return of it will
+    be used as the tenant.
+    - `assign`: the name of the assign where we must save the tenant.
+  - For `Triplex.EnsurePlug`
+    - `callback`: function that might be called when the plug succeeded. It
+    must return a connection.
+    - `failure_callback`: function that might be called when the plug failed.
+    It must return a connection.
+  - For `Triplex.ParamPlug`
+    - `param`: the param name to load the tenant from.
+  - For `Triplex.SessionPlug`
+    - `session`: the session param name to load the tenant from.
+  - For `Triplex.SubdomainPlug`
+    - `endpoint`: the Phoenix.Endpoint to get the host name to dicover the
+    subdomain.
   """
 
   defstruct [
@@ -42,8 +33,11 @@ defmodule Triplex.PlugConfig do
     session: :tenant
   ]
 
-  def new(opts \\ []),
-    do: __MODULE__ |> struct(opts) |> normalize_param()
+  @doc """
+  Creates a new `%Plug.Config{}`, normalizing the needed arguments.
+  """
+  def new(args \\ []),
+    do: __MODULE__ |> struct(args) |> normalize_param()
 
   defp normalize_param(%{param: param} = struct) when is_atom(param),
     do: Map.put(struct, :param, Atom.to_string(param))

lib/triplex/session_plug.ex

@@ -9,7 +9,7 @@ defmodule Triplex.SessionPlug do
         session: :subdomain,
         tenant_handler: &TenantHelper.tenant_handler/1
 
-  See `Triplex.PlugConfig` to check all the allowed configuration flags.
+  See `Triplex.PlugConfig` to check all the allowed `config` flags.
   """
 
   import Triplex.Plug

lib/triplex/subdomain_plug.ex

@@ -9,7 +9,7 @@ defmodule Triplex.SubdomainPlug do
         endpoint: MyApp.Endpoint,
         tenant_handler: &TenantHelper.tenant_handler/1
 
-  See `Triplex.PlugConfig` to check all the allowed configuration flags.
+  See `Triplex.PlugConfig` to check all the allowed `config` flags.
   """
 
   import Triplex.Plug

mix.exs

@@ -4,7 +4,7 @@ defmodule Triplex.Mixfile do
   def project do
     [
       app: :triplex,
-      version: "1.1.1",
+      version: "1.1.2",
       elixir: "~> 1.4",
 
       description: description(),