Add documentation and typespecs (#32)

Author: jessedijkstra

lib/ex_cell/adapter.ex

@@ -1,4 +1,18 @@
 defmodule ExCell.Adapter do
-  @moduledoc false
-  @callback container(Map.t) :: {:safe, List.t}
+  @moduledoc """
+  An ExCell Adapter defines the way the adapter outputs its HTML. The adapter
+  requires a function called adapter that accepts a map container name,
+  attributes, params and the content. It should return a Phoenix.HTML safe string.
+  """
+
+  @type html :: {:safe, list()}
+
+  @type options :: %{
+    required(:name) => String.t,
+    required(:attributes) => list(),
+    required(:params) => map(),
+    required(:content) => String.t | {:safe, list()}
+  }
+
+  @callback container(options :: options()) :: html()
 end

lib/ex_cell/adapters/cell_js.ex

@@ -1,5 +1,20 @@
 defmodule ExCell.Adapters.CellJS do
-  @moduledoc false
+  @moduledoc """
+  The CellJS adapter can be used to output the cells as HTML compatible with
+  [cells-js](https://github.com/DefactoSoftware/cells-js). CellsJS was written
+  with ExCell in  mind.
+
+  Tags are automatically closed when they are part of the
+  [void elements](https://stackoverflow.com/questions/4693939/self-closing-tags-void-elements-in-html5)
+  specification.
+
+  CellsJS are uses two predefined attributes to parse the Javascript. First it
+  will look for the `data-cell` cell attribute and match it to the defined Cell
+  in Javascript.
+
+  Second it will take the JSON arguments set on the `data-cell-params` attribute
+  and use that to initialize the cell with user defined parameters.
+  """
 
   @behaviour ExCell.Adapter
 
@@ -27,11 +42,19 @@ defmodule ExCell.Adapters.CellJS do
   def void_element?(tag) when is_atom(tag), do: void_element?(Atom.to_string(tag))
   def void_element?(tag), do: tag in void_elements()
 
+  @doc """
+  The data_attribute function is used to build up the data attributes and set
+  the default `data-cell` and `data-cell-params` attributes.
+  """
   def data_attribute(name, data \\ [], params \\ %{})
   def data_attribute(name, nil, params), do: data_attribute(name, [], params)
   def data_attribute(name, data, params) when is_list(data), do:
     Keyword.merge(data, cell: name, cell_params: Poison.encode!(params))
 
+  @doc """
+  The attributes function is used to auto fill the attributes for a container
+  with the data attributes.
+  """
   def attributes(name, attributes \\ [], params \\ %{}) do
     Keyword.put(
       attributes,
@@ -40,6 +63,10 @@ defmodule ExCell.Adapters.CellJS do
     )
   end
 
+  @doc """
+  The container renders HTML with the attributes, class name and data attributes
+  prefilled. The HTML is rendered with Phoenix.HTML.Tag.
+  """
   def container(%{
     name: name,
     attributes: attributes,

lib/ex_cell/ex_cell.ex

@@ -1,5 +1,33 @@
 defmodule ExCell do
-  @moduledoc false
+  @moduledoc """
+  ExCell is used to split larger views in smaller cells that can be reused and
+  easily packaged with Javascript and CSS.
+
+  A cell consists of a couple of files:
+  ```
+  cells
+  |- avatar
+  |  |- template.html.eex
+  |  |- view.html.eex
+  |  |- style.css (optional)
+  |  |- index.js (optional)
+  |- header
+  ...
+  ```
+
+  You can render the cell in a view, controller or another cell by adding the following code:
+  ```ex
+  cell(AvatarCell, class: "CustomClassName", user: %User{})
+  ```
+
+  This would generate the following HTML when you render the cell:
+
+  ```html
+  <span class="AvatarCell" data-cell="AvatarCell" data-cell-params="{}">
+    <img src="/images/foo/avatar.jpg" class="AvatarCell-Image" alt="foo" />
+  </span>
+  ```
+  """
   @dialyzer [{:no_match, relative_name: 2}]
 
   def module_relative_to(module, relative_to) do