From c0eb9ec41f5d3103459bb2067cb2511baa219d1f Mon Sep 17 00:00:00 2001
From: Martin Frost <frost@ceri.se>
Date: Wed, 27 May 2015 19:33:15 +0200
Subject: [PATCH] Added better documentation.

---
 .gitignore |  1 +
 README.md  | 10 ++++++++
 lib/isn.ex | 70 ++++++++++++++++++++++++++++++++++++++++++++++++++----
 3 files changed, 77 insertions(+), 4 deletions(-)

diff --git a/.gitignore b/.gitignore
index 755b605..5b7eb28 100644
--- a/.gitignore
+++ b/.gitignore
@@ -3,3 +3,4 @@
 /deps
 erl_crash.dump
 *.ez
+docs
diff --git a/README.md b/README.md
index cc4b128..1b47355 100644
--- a/README.md
+++ b/README.md
@@ -13,6 +13,16 @@ defp deps do
 end
 ```
 
+2. Add the isn extension to your database
+
+```elixir
+{:ok, pid} = Postgrex.Connection.start_link(
+  hostname: "localhost",
+  database: "isn_test"
+)
+Postgrex.Connection.query!(pid, "CREATE EXTENSION isn;", [])
+```
+
 2. Register the postgrex extension
 
 ```elixir
diff --git a/lib/isn.ex b/lib/isn.ex
index 471ffd0..4aeef6f 100644
--- a/lib/isn.ex
+++ b/lib/isn.ex
@@ -4,6 +4,41 @@ defmodule Isn do
   @behaviour Postgrex.Extension
   @isn ~w(ean13 isbn13 ismn13 issn13 isbn ismn issn upc)
 
+  @moduledoc """
+  A Postgrex.Extension enabling the use of postgresql data types from the isn
+  extension.
+
+  Add this module as an extension when establishing your Postgrex connection:
+
+      Postgrex.Connection.start_link(
+        database: "isn_test",
+        extensions: [{Isn, {}}])
+
+  Then you can do Ecto.Migrations like this:
+
+      defmodule MyApp.Repo.Migrations.CreateBook do
+        use Ecto.Migration
+
+        def change do
+          create table(:books) do
+            add :isbn, :isbn13
+            # other fields
+          end
+        end
+      end
+
+  You can also define Ecto.Models using the matching custom Ecto.Types:
+
+      defmodule MyApp.Book do
+        use MyApp.Web, :model
+
+        schema "books" do
+          field :isbn, Isn.ISBN13
+          # other fields
+        end
+      end
+  """
+
   def init(parameters, _opts),
     do: parameters
 
@@ -21,13 +56,40 @@ defmodule Isn do
 end
 
 defmodule Isn.Base do
+  @moduledoc """
+  Base module for Isn custom ecto types.
+  """
+
+  @doc """
+  Set up basic functionality for an Isn type.
+
+  This extends the calling module by defining implementations for
+
+  * type/0
+  * blank?/0
+  * cast/1
+  * load/1
+  * dump/1
+  """
   defmacro __using__(isn_type) do
-    quote bind_quoted: [isn_type: isn_type] do
-      # @behaviour Ecto.Type
-      #
+    ecto_type = isn_type |> Atom.to_string |> String.upcase
+    quote bind_quoted: [isn_type: isn_type, ecto_type: ecto_type] do
+      @behaviour Ecto.Type
       @isn_type isn_type
+
       @moduledoc """
-      Definition for the #{@isn_type} module.
+      Definition for the #{isn_type} module.
+
+      How to use this in an Ecto.Model
+
+          defmodule MyApp.Book do
+            use MyApp.Web, :model
+
+            schema "books" do
+              field :#{isn_type}, Isn.#{ecto_type}
+              # other fields
+            end
+          end
       """
 
       def type,