Misc doc changes (#20)

List of changes:
- add badges for quick links to essential module info
- add license to generated HTML doc
- bump ex_doc to latest version
- fix typo via `codespell`
- fix wordings and Markdown

LICENSE → LICENSE.md

@@ -1,4 +1,4 @@
-MIT License
+# MIT License
 
 Copyright (c) 2018 Frame.io
 

README.md

@@ -1,19 +1,26 @@
 # ExlasticSearch
 
-An elasticsearch DSL for mapping Ecto models to elasticsearch mappings, along with elixir
-friendly query wrappers, response formatting and the like.
+[![Module Version](https://img.shields.io/hexpm/v/exlasticsearch.svg)](https://hex.pm/packages/exlasticsearch)
+[![Hex Docs](https://img.shields.io/badge/hex-docs-lightgreen.svg)](https://hexdocs.pm/exlasticsearch/)
+[![Total Download](https://img.shields.io/hexpm/dt/exlasticsearch.svg)](https://hex.pm/packages/exlasticsearch)
+[![License](https://img.shields.io/hexpm/l/exlasticsearch.svg)](https://github.com/Frameio/exlasticsearch/blob/master/LICENSE)
+[![Last Updated](https://img.shields.io/github/last-commit/Frameio/exlasticsearch.svg)](https://github.com/Frameio/exlasticsearch/commits/master)
+
+An [Elasticsearch](https://www.elastic.co/elasticsearch/) DSLs for mapping Ecto
+models to Elasticsearch mappings, along with Elixir friendly query wrappers,
+response formatting and the like.
 
 ## Installation
 
 ```elixir
 def deps do
   [
-    {:exlasticsearch, "~> 1.3.3"}
+    {:exlasticsearch, "~> 2.2.3"}
   ]
 end
 ```
 
-Docs are available on [hex](https://hexdocs.pm/exlasticsearch/0.2.2)
+Docs are available on [hex](https://hexdocs.pm/exlasticsearch/)
 
 ## Usage
 
@@ -46,16 +53,22 @@ A repo model like Ecto is provided, so a with ability to do most restful operati
 addition to calling search APIs with the query structs above.
 
 If additional data needs to be fetched or formatted prior to insertion into elastic, the `ExlasticSearch.Indexable`
-protocol can be implemented to do that for you.  A default implementation can also be generated as part of using
+protocol can be implemented to do that for you. A default implementation can also be generated as part of using
 the `ExlasticSearch.Model` macro.
 
 ## Configuration
 
-This library requires `elastix` (an elixir elasticsearch http client).  So refer to it for any http related configuration. In addition, there are the following configuration options:
+This library requires [Elastix](https://hex.pm/packages/elastix), an Elixir Elasticsearch HTTP client. So refer to it for any HTTP related configuration. In addition, there are the following configuration options:
 
 ```elixir
 config :exlasticsearch, :type_inference, ExlasticSearch.TypeInference
 
 config :exlasticsearch, ExlasticSearch.Repo,
   url: "http://localhost:9200"
 ```
+
+## Copyright and License
+
+Copyright (c) 2018 Frame.io
+
+This software is released under the [MIT License](./LICENSE.md).

lib/exlasticsearch.ex

@@ -1,6 +1,6 @@
 defmodule ExlasticSearch do
   @moduledoc """
-  A collection of elasticsearch DSL's to make development simple.
+  A collection of Elasticsearch DSL's to make development simple.
 
   The usage is meant to pair with existing ecto schema, like so:
 
@@ -23,7 +23,7 @@ defmodule ExlasticSearch do
       |> should(match_phrase(field, value, opts))
       |> filter(term(filter_field, value))
 
-  A repo model like ecto is provided, so a with ability to do most restful operations on records, in
+  A Repo model like Ecto is provided, so a with ability to do most restful operations on records, in
   addition to calling search apis with the query structs above.
 
   If additional data needs to be fetched or formatted prior to insertion into elastic, the `ExlasticSearch.Indexable`

lib/exlasticsearch/aggregation.ex

@@ -1,13 +1,13 @@
 defmodule ExlasticSearch.Aggregation do
   @moduledoc """
-  Elasticsearch aggregation building functions
+  Elasticsearch aggregation building functions.
   """
 
   defstruct aggregations: [], nested: %{}, options: %{}
 
   @type t :: %__MODULE__{}
 
-  @doc "create a new aggregation specification"
+  @doc "Create a new aggregation specification."
   def new, do: %__MODULE__{}
 
   @doc """
@@ -18,34 +18,34 @@ defmodule ExlasticSearch.Aggregation do
   end
 
   @doc """
-  A composite aggregation
+  A composite aggregation.
   """
   def composite(%{aggregations: aggs} = agg, name, sources, opts \\ []) do
     options = Map.new(opts)
     %{agg | aggregations: [{name, %{composite: Map.merge(%{sources: sources}, options)}} | aggs]}
   end
 
   @doc """
-  The source for a composite aggregation, eg `composite_source(:age, :terms, field: :age)`
+  The source for a composite aggregation, eg `composite_source(:age, :terms, field: :age)`.
   """
   def composite_source(name, type, opts), do: %{name => %{type => Map.new(opts)}}
 
   @doc """
-  Return the top results for a query or aggregation scope
+  Return the top results for a query or aggregation scope.
   """
   def top_hits(%{aggregations: aggs} = agg, name, options) do
     %{agg | aggregations: [{name, %{top_hits: Map.new(options)}} | aggs]}
   end
 
   @doc """
-  Includes a given aggregation within the aggregation with name `name`
+  Includes a given aggregation within the aggregation with name `name`.
   """
   def nest(%{nested: nested} = agg, name, nest) do
     %{agg | nested: Map.put(nested, name, nest)}
   end
 
   @doc """
-  Convert to the es representation of the aggregation
+  Convert to the es representation of the aggregation.
   """
   def realize(%__MODULE__{aggregations: aggs, nested: nested, options: opts}) do
     %{

lib/exlasticsearch/bulk.ex

@@ -1,13 +1,13 @@
 defmodule ExlasticSearch.BulkOperation do
   @moduledoc """
-  Handles bulk request generation
+  Handles bulk request generation.
   """
 
   alias ExlasticSearch.Indexable
 
   @doc """
   Generates a request for inserts, updates and deletes
-  that can be sent as a bulk request using Elastix
+  that can be sent as a bulk request using Elastix.
   """
   def bulk_operation({:delete, _struct, _index} = instruction), do: bulk_operation_delete(instruction)
 

lib/exlasticsearch/indexable.ex

@@ -1,26 +1,27 @@
 defprotocol ExlasticSearch.Indexable do
   @moduledoc """
-  Protocol for converting Ecto structs to ES-compatible maps.  `ExlasticSearch.Repo` uses
-  this internally to effect any conversion prior to communicating with elasticsearch itself
+  Protocol for converting Ecto structs to ES-compatible maps.
+
+  `ExlasticSearch.Repo` uses this internally to effect any conversion prior to communicating with Elasticsearch itself.
   """
 
-  @doc "ES record id"
+  @doc "ES record id."
   @spec id(struct) :: binary
   def id(_)
 
-  @doc "Properties map to be inserted into ES"
+  @doc "Properties map to be inserted into ES."
   @spec document(struct, atom) :: map
   def document(_, _)
 
-  @doc "Properties map to be inserted into ES"
+  @doc "Properties map to be inserted into ES."
   @spec document(struct) :: map
   def document(_)
 
-  @doc "Any preloads needed to call `document/2`"
+  @doc "Any preloads needed to call `document/2`."
   @spec preload(struct, atom) :: struct
   def preload(_, _)
 
-  @doc "Any preloads needed to call `document/2`"
+  @doc "Any preloads needed to call `document/2`."
   @spec preload(struct) :: struct
   def preload(_)
 end

lib/exlasticsearch/model.ex

@@ -1,7 +1,8 @@
 defmodule ExlasticSearch.Model do
   @moduledoc """
-  Base macro for generating elasticsearch modules.  Is intended to be used in conjunction with a
-  Ecto model (although that is not strictly necessary).
+  Base macro for generating elasticsearch modules.
+
+  Is intended to be used in conjunction with a Ecto model (although that is not strictly necessary).
 
   It includes three primary macros:
 
@@ -66,12 +67,15 @@ defmodule ExlasticSearch.Model do
   end
 
   @doc """
-  Opens up index definition for the current model.  Will name the index and generate metadata
-  attributes for the index based on subsequent calls to `settings/1` and `mappings/2`.
+  Opens up index definition for the current model.
+
+  Will name the index and generate metadata attributes for the index based on subsequent calls to `settings/1` and `mappings/2`.
+
+  Accepts:
+
+    * `type` - the indexes type (and index name will be `type <> "s"`)
+    * `block` - the definition of the index
 
-  Accepts
-  * `type` - the indexes type (and index name will be `type <> "s"`)
-  * `block` - the definition of the index
   """
   defmacro indexes(type, block) do
     quote do
@@ -124,7 +128,7 @@ defmodule ExlasticSearch.Model do
 
   defmodule SearchResult do
     @moduledoc """
-    Wrapper for a models search result.  Used for response parsing
+    Wrapper for a models search result. Used for response parsing.
     """
     defmacro __using__(_) do
       columns = __CALLER__.module.__mappings__()
@@ -139,12 +143,15 @@ defmodule ExlasticSearch.Model do
   end
 
   @doc """
-  Adds a new mapping to the ES schema.  The type of the mapping will be inferred automatically, unless explictly set
-  in props.
+  Adds a new mapping to the ES schema.
+
+  The type of the mapping will be inferred automatically, unless explicitly set in props.
 
   Accepts:
+
     * `name` - the name of the mapping
     * `props` - is a map/kw list of ES mapping configuration (e.g. `search_analyzer: "my_search_analyzer", type: "text"`)
+
   """
   defmacro mapping(name, props \\ []) do
     quote do
@@ -153,7 +160,7 @@ defmodule ExlasticSearch.Model do
   end
 
   @doc """
-  A map of index settings.  Structure is the same as specified by ES.
+  A map of index settings. Structure is the same as specified by ES.
   """
   defmacro settings(settings) do
     quote do
@@ -186,7 +193,7 @@ defmodule ExlasticSearch.Model do
   end
 
   @doc """
-  Converts a search result to `model`'s search result type
+  Converts a search result to `model`'s search result type.
   """
   def es_decode(source, model) do
     do_decode(model.__es_decode_template__(), source)