Add documentation for new macros

lib/rummage_ecto/hooks/custom_sort.ex

@@ -56,6 +56,3 @@ defmodule Rummage.Ecto.Hook.CustomSort do
     |> Map.put_new(:order, :asc)
   end
 end
-
-
-

lib/rummage_ecto/schema.ex

@@ -8,6 +8,33 @@ defmodule Rummage.Ecto.Schema do
 
   @rummage_scope_types ~w{search sort paginate custom_search custom_sort custom_paginate}a
 
+  @doc """
+  This macro allows us to leverage features in `Rummage.Ecto.Schema`. It takes
+  advantage of `Ecto`, `rummage_field` and `rummage_scope`
+
+  ## Usage:
+
+  ```elixir
+  defmodule MySchema do
+    use Rummage.Ecto.Schema
+
+    schema "my_table" do
+      field :field1, :integer
+      field :field2, :integer
+
+      timestamps()
+    end
+
+    rummage_field :field1_or_field2 do
+      {:fragment, "coalesce(?, ?)", :name, :description}
+    end
+
+    rummage_scope :show_page, [type: :paginate], fn(page) ->
+      %{per_page: 10, page: page}
+    end
+  end
+  ```
+  """
   defmacro __using__(opts) do
     quote do
       use Ecto.Schema
@@ -17,6 +44,34 @@ defmodule Rummage.Ecto.Schema do
     end
   end
 
+  @doc """
+  Rummage Field is a way to define a field which can be used to search, sort,
+  paginate through. This field might not exist in the database or the schema,
+  but can be represented as a `fragments` query using multiple fields.
+
+  NOTE: Currently this feature has some limitations due to limitations put on
+  Ecto's fragments. Ecto 3.0 is expected to come out with `unsafe_fragment`,
+  which will give this feature great flexibility. This feature is also quite
+  dependent on what database engine is being used. For now, we have made
+  a few fragments available (the list can be seen [here]()) which are thoroughly
+  tested on postgres. If these fragments don't do it, you can use `rummage_scope`
+  to accomplish a similar functionality.
+
+  ## Usage:
+
+  To use upper case name as rummage field:
+
+  ```elixir
+  rummage_field :upper_case_name do
+    {:fragment, "upper(?)", :name}
+  end
+  ```
+
+  To use the hour for created_at as rummage field:
+  rummage_field :created_at_hour do
+    {:fragment, "date_part('hour', ?)", :inserted_at}
+  end
+  """
   defmacro rummage_field(field, do: block) do
     name = :"__rummage_field_#{field}"