Organize modules in ExDoc

bin/docs

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+#
+# Generate Documentation
+#
+# Creates HTML documentation and opens it in your local browser.
+
+mix docs || { echo 'Docs did not generate!'; exit 1; }
+open doc/index.html || { echo 'Could not open docs in local browser!'; exit 1; }

lib/elasticsearch.ex

@@ -1,6 +1,14 @@
 defmodule Elasticsearch do
   @moduledoc """
-  An Elixir interface to the Elasticsearch API.
+  An Elixir interface to the Elasticsearch JSON API.
+
+  ## Configuration
+
+  You can customize the API module used by this module to make requests to
+  the Elasticsearch API. (Default: `Elasticsearch.API.HTTP`)
+
+      config :elasticsearch,
+        api_module: MyApp.CustomAPI
   """
 
   alias Elasticsearch.Document
@@ -525,4 +533,4 @@ defmodule Elasticsearch do
   defp config do
     Application.get_all_env(:elasticsearch)
   end
-end
+end

lib/elasticsearch/api.ex

@@ -1,6 +1,7 @@
 defmodule Elasticsearch.API do
   @moduledoc """
-  A behaviour that an Elasticsearch API must adhere to.
+  Defines the necessary callbacks for integrating with the Elasticsearch
+  JSON API.
   """
 
   @type url :: String.t()
@@ -16,4 +17,4 @@ defmodule Elasticsearch.API do
   @callback put(url, data, headers, opts) :: response
   @callback post(url, data, headers, opts) :: response
   @callback delete(url, headers, opts) :: response
-end
+end

lib/elasticsearch/config.ex

@@ -1,6 +1,6 @@
 defmodule Elasticsearch.Config do
   @moduledoc """
-  Conveniences for fetching configuration values for `Elasticsearch`.
+  Convenience functions for fetching configuration values for `Elasticsearch`.
   """
 
   alias Elasticsearch.Store
@@ -93,6 +93,10 @@ defmodule Elasticsearch.Config do
     all()[:indexes][index]
   end
 
+  @doc """
+  Returns all configuration values for `Elasticsearch`.
+  """
+  @spec all :: Keyword.t()
   def all do
     Application.get_all_env(:elasticsearch)
   end

lib/elasticsearch/data_stream.ex

@@ -1,11 +1,7 @@
 defmodule Elasticsearch.DataStream do
   @moduledoc """
-  Functions for building `Stream`s using the configured 
-  `Elasticsearch.Store`.
-
-      config :elasticsearch,
-        # A module that implements the Elasticsearch.Store behaviour
-        store: MyApp.ElasticsearchStore
+  Functions for building `Stream`s using the configured `Elasticsearch.Store`.
+  See `stream/2`.
   """
 
   @type source :: any

lib/elasticsearch/executable.ex

@@ -19,10 +19,12 @@ defmodule Elasticsearch.Executable do
 
   use GenServer
 
+  @doc false
   def start_link(name, executable, port_number) do
     GenServer.start_link(__MODULE__, [name, executable, port_number])
   end
 
+  @doc false
   def init([name, executable, port_number]) do
     case System.cmd("lsof", ["-i", ":#{port_number}"]) do
       {"", _} ->
@@ -37,4 +39,4 @@ defmodule Elasticsearch.Executable do
         {:ok, nil}
     end
   end
-end
+end

lib/mix/elasticsearch.build.ex

@@ -13,7 +13,7 @@ defmodule Mix.Tasks.Elasticsearch.Build do
 
   ## Example
 
-      $ mix elasticsearch.build posts {index2} {index3}
+      $ mix elasticsearch.build posts [index2] [index3]
 
   To build an index only if it does not exist, use the `--existing` option:
       

lib/mix/elasticsearch.install.ex

@@ -3,10 +3,9 @@ defmodule Mix.Tasks.Elasticsearch.Install do
   FOR DEVELOPMENT USE ONLY.
 
   This task is provided as a convenient way to install a particular version
-  of Elasticsearch for your project on a development machine.
-
-  Use `Elasticsearch.Executable` to add the executables to your app's
-  supervision tree in the Mix `:dev` environment.
+  of Elasticsearch for your project on a development machine. Use
+  `Elasticsearch.Executable` to add the executables to your app's supervision
+  tree in the Mix `:dev` environment.
 
   ## Example
 
@@ -67,4 +66,4 @@ defmodule Mix.Tasks.Elasticsearch.Install do
     System.cmd("rm", [tar], cd: location)
     System.cmd("mv", [name, alias], cd: location)
   end
-end
+end

mix.exs

@@ -6,8 +6,8 @@ defmodule Elasticsearch.Mixfile do
       app: :elasticsearch,
       version: "0.1.0",
       elixir: "~> 1.5",
-      start_permanent: Mix.env == :prod,
-      elixirc_paths: elixirc_paths(Mix.env),
+      start_permanent: Mix.env() == :prod,
+      elixirc_paths: elixirc_paths(Mix.env()),
       docs: docs(),
       deps: deps()
     ]
@@ -23,7 +23,7 @@ defmodule Elasticsearch.Mixfile do
 
   # Specifies which paths to compile per environment
   defp elixirc_paths(env) when env in ~w(test dev)a, do: ["lib", "test/support"]
-  defp elixirc_paths(_),     do: ["lib"]
+  defp elixirc_paths(_), do: ["lib"]
 
   # Run "mix help deps" to learn about dependencies.
   defp deps do
@@ -38,7 +38,29 @@ defmodule Elasticsearch.Mixfile do
   defp docs do
     [
       main: "README",
-      extras: ["README.md"]
+      extras: ["README.md"],
+      groups_for_modules: [
+        API: [
+          Elasticsearch,
+          Elasticsearch.API,
+          Elasticsearch.API.HTTP
+        ],
+        Config: [
+          Elasticsearch.Config
+        ],
+        Indexing: [
+          Elasticsearch.Builder,
+          Elasticsearch.Bulk
+        ],
+        Storage: [
+          Elasticsearch.DataStream,
+          Elasticsearch.Document,
+          Elasticsearch.Store
+        ],
+        Development: [
+          Elasticsearch.Executable
+        ]
+      ]
     ]
   end
-end
+end