Misc doc changes

Besides other documentation changes, this commit ensures the generated
HTML doc for HexDocs.pm will become the source of truth for this Elixir
library and leverage on latest features of ExDoc.

.formatter.exs

@@ -1,4 +1,4 @@
 # Used by "mix format"
 [
-  inputs: ["mix.exs", "{config,lib,test}/**/*.{ex,exs}"]
+  inputs: ["{mix,.formatter}.exs", "{config,lib,test}/**/*.{ex,exs}"]
 ]

.gitignore

@@ -7,7 +7,7 @@
 # The directory Mix downloads your dependencies sources to.
 /deps/
 
-# Where 3rd-party dependencies like ExDoc output generated docs.
+# Where third-party dependencies like ExDoc output generated docs.
 /doc/
 
 # Ignore .fetch files in case you like to edit your project deps locally.
@@ -22,6 +22,9 @@ erl_crash.dump
 # Ignore package tarball (built via "mix hex.build").
 exlasticsearch-*.tar
 
-.elixir_ls/
+# Temporary files for e.g. tests
+/tmp/
+
+# Misc.
 /tags
 /TAGS

LICENSE → LICENSE.md

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

README.md

@@ -1,7 +1,14 @@
 # ExlasticSearch
 
-An elasticsearch dsls 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
 
@@ -13,11 +20,11 @@ def deps do
 end
 ```
 
-Docs are available on [hex](https://hexdocs.pm/exlasticsearch/0.2.2)
+Docs are available on [hex](https://hexdocs.pm/exlasticsearch/)
 
 ## Usage
 
-You can pair an ExlasticSearch.Model with an existing schema like:
+You can pair an `ExlasticSearch.Model` with an existing schema like:
 
 ```elixir
 defmodule MySchema do
@@ -37,21 +44,21 @@ You can then construct queries like so:
 
 ```elixir
 MySchema.search_query()
-|> must(math(field, value))
-|> should(match_phrash(field, value, opts))
+|> must(match(field, value))
+|> 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
-addition to calling search apis with the query structs above.
+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`
 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 config options:
+This library requires `elastix` (an Elixir Elasticsearch HTTP client).  So refer to it for any HTTP related configuration.  In addition, there are the following config options:
 
 ```elixir
 config :exlasticsearch, :type_inference, ExlasticSearch.TypeInference
@@ -61,3 +68,9 @@ config :exlasticsearch, :monitoring, ExlasticSearch.Monitoring.Mock
 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,9 +1,9 @@
 defmodule ExlasticSearch do
   @moduledoc """
-  A collection of elasticsearch dsl's to make development simple.  The usage is meant to
-  pair with existing ecto schema, like so:
+  A collection of Elasticsearch DSLs to make development simple.  The usage is meant to
+  pair with existing Ecto schema, like so:
 
-  ```
+  ```elixir
   defmodule MySchema do
     ...
     use ExlasticSearch.Model
@@ -19,14 +19,14 @@ defmodule ExlasticSearch do
 
   You can then construct queries like so:
 
-  ```
+  ```elixir
   MySchema.search_query()
-  |> must(math(field, value))
+  |> must(match(field, value))
   |> 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,51 +1,51 @@
 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 """
-  Bucket a query by a given term
+  Bucket a query by a given term.
   """
   def terms(%{aggregations: aggs} = agg, name, options) do
     %{agg | aggregations: [{name, %{terms: Enum.into(options, %{})}} | aggs]}
   end
 
   @doc """
-  A composite aggregation
+  A composite aggregation.
   """
   def composite(%{aggregations: aggs} = agg, name, sources, opts \\ []) do
     options = Enum.into(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 => Enum.into(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: Enum.into(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
     %{aggs: Enum.into(aggs, %{}, fn {key, agg} -> {key, with_nested(realize(agg), nested, key)} end)

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,28 @@
 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,9 @@
 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:
 
@@ -11,7 +13,7 @@ defmodule ExlasticSearch.Model do
 
   The usage is something like this
 
-  ```
+  ```elixir
   indexes :my_type do
     settings Application.get_env(:some, :settings)
 
@@ -60,8 +62,10 @@ 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"`)
@@ -122,7 +126,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__()
@@ -136,7 +140,9 @@ 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
+  Adds a new mapping to the ES schema.
+
+  The type of the mapping will be inferred automatically, unless explictly set
   in props.
 
   Accepts:
@@ -150,7 +156,9 @@ 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
@@ -183,7 +191,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
     model.__es_decode_template__()

lib/exlasticsearch/monitoring/mock.ex

@@ -1,6 +1,8 @@
 defmodule ExlasticSearch.Monitoring.Mock do
   @moduledoc """
-  Noop implementation of monitoring.  To bring your own, do  `config :exlasticsearch, :monitoring, MonitoringModule`
+  Noop implementation of monitoring.
+
+  To bring your own, do  `config :exlasticsearch, :monitoring, MonitoringModule`
   """
   def increment(_, _), do: nil
-end
+end