Add more detail to API docs, and add client arg to README examples (#13)

Author: mjm

README.md

@@ -40,18 +40,26 @@ All responses are deserialized into maps before returning one of these responses
 
 ## Examples
 
+### Creating a client
+
+All API function that make requests require a client.
+
+```elixir
+client = Algolia.new()
+```
+
 ### Searching
 
 #### Searching an index
 
 ```elixir
-"my_index" |> Algolia.search("some query")
+Algolia.search(client, "my_index", "some query")
 ```
 
 With options:
 
 ```elixir
-"my_index" |> Algolia.search("some query", attributesToRetrieve: "firstname", hitsPerPage: 20)
+Algolia.search(client, "my_index", "some query", attributesToRetrieve: "firstname", hitsPerPage: 20)
 ```
 
 See all available search options [**here**](https://www.algolia.com/doc/rest#full-text-search-parameters).
@@ -61,16 +69,16 @@ See all available search options [**here**](https://www.algolia.com/doc/rest#ful
 Browsing is like search but skips most ranking and allows fetching more results at once.
 
 ```elixir
-"my_index" |> Algolia.browse("some query", filter: "color:red")
+Algolia.browse(client, "my_index", query: "some query", filter: "color:red")
 ```
 
 #### Multiple queries at once
 
 ```elixir
-Algolia.multi([
-    %{index_name => "my_index1", query: "search query"},
-    %{index_name => "my_index2", query: "another query", hitsPerPage: 3,},
-    %{index_name => "my_index3", query: "3rd query", tagFilters: "promotion"}])
+Algolia.multi(client, [
+  %{index_name: "my_index1", query: "search query"},
+  %{index_name: "my_index2", query: "another query", hitsPerPage: 3},
+  %{index_name: "my_index3", query: "3rd query", tagFilters: "promotion"}
 ])
 ```
 
@@ -80,7 +88,7 @@ You can specify a strategy to optimize your multiple queries:
 - `stop_if_enough_matches`: Execute the sequence of queries until the number of hits is reached by the sum of hits.
 
 ```elixir
-Algolia.multi([query1, query2], strategy: :stop_if_enough_matches)
+Algolia.multi(client, [query1, query2], strategy: :stop_if_enough_matches)
 ```
 
 ### Saving
@@ -91,123 +99,125 @@ Save a single object to index without specifying objectID. You must have `object
 inside object, or use the `id_attribute` option (see below).
 
 ```elixir
-"my_index" |> Algolia.save_object(%{objectID: "1"})
+Algolia.save_object(client, "my_index", %{objectID: "1"})
 ```
 
 Save a single object with a given objectID:
 
 ```elixir
-"my_index" |> Algolia.save_object(%{title: "hello"}, "12345")
+Algolia.save_object(client, "my_index", %{title: "hello"}, "12345")
 ```
 
 Save multiple objects to an index:
 
 ```elixir
-"my_index" |> Algolia.save_objects([%{objectID: "1"}, %{objectID: "2"}])
+Algolia.save_objects(client, "my_index", [%{objectID: "1"}, %{objectID: "2"}])
 ```
 
 ### Updating
 
 Partially update a single object:
 
 ```elixir
-"my_index" |> Algolia.partial_update_object(%{title: "hello"}, "12345")
+Algolia.partial_update_object(client, "my_index", %{title: "hello"}, "12345")
 ```
 
 Update multiple objects. You must have `objectID` in each object, or use the `id_attribute` option (see below).
 
 ```elixir
-"my_index" |> Algolia.partial_update_objects([%{objectID: "1"}, %{objectID: "2"}])
+Algolia.partial_update_objects(client, "my_index", [%{objectID: "1"}, %{objectID: "2"}])
 ```
 
 Partial update by default creates a new object if an object does not exist at the
 objectID. You can turn this off by passing `false` to the `:upsert?` option.
 
 ```elixir
-"my_index" |> Algolia.partial_update_object(%{title: "hello"}, "12345", upsert?: false)
-"my_index" |> Algolia.partial_update_objects([%{id: "1"}, %{id: "2"}], id_attribute: :id, upsert?: false)
+Algolia.partial_update_object(client, "my_index", %{title: "hello"}, "12345", upsert?: false)
+Algolia.partial_update_objects(client, "my_index", [%{id: "1"}, %{id: "2"}], id_attribute: :id, upsert?: false)
 ```
 
-
 ### `id_attribute` option
 
 All write functions such as `save_object` and `partial_update_object` come with an `id_attribute` option that lets
 you specify the `objectID` from an existing field in the object, so you do not have to generate it yourself.
 
 ```elixir
-"my_index" |> Algolia.save_object(%{id: "2"}, id_attribute: :id)
+Algolia.save_object(client, "my_index", %{id: "2"}, id_attribute: :id)
 ```
 
 It also works for batch operations, such as `save_objects` and `partial_update_objects`:
 
 ```elixir
-"my_index" |> Algolia.save_objects([%{id: "1"}, %{id: "2"}], id_attribute: :id)
+Algolia.save_objects(client, "my_index", [%{id: "1"}, %{id: "2"}], id_attribute: :id)
 ```
 
-
 ### Wait for task
 
 All write operations can be waited on by simply piping the response into `wait/1`:
 
 ```elixir
-"my_index" |> Algolia.save_object(%{id: "123"}) |> Algolia.wait()
+client
+|> Algolia.save_object("my_index", %{id: "123"})
+|> Algolia.wait(client)
 ```
 
 The client polls the server to check the status of the task.
 You can specify a time (in milliseconds) between each tick of the poll; the default is 1000ms (1 second).
 
 ```elixir
-"my_index" |> Algolia.save_object(%{id: "123"}) |> Algolia.wait(2_000)
+client
+|> Algolia.save_object("my_index", %{id: "123"})
+|> Algolia.wait(client, retry_delay: 2_000)
 ```
 
-You can also explicitly pass a `taskID` to `wait`:
+You can also explicitly pass a `taskID` to `wait_task`:
 
 
 ```elixir
 {:ok, %{"taskID" => task_id, "indexName" => index}}
-  = "my_index" |> Algolia.save_object(%{id: "123"})
+  = Algolia.save_object(client, "my_index", %{id: "123"})
 
-Algolia.wait(index, task_id)
+Algolia.wait_task(client, index, task_id)
 ```
 
 Optionally including the poll interval:
 
 ```elixir
-Algolia.wait(index, task_id, 2_000)
+Algolia.wait(client, index, task_id, retry_delay: 2_000)
 ```
 
 ### Index related operations
 
 #### Listing all indexes
 
 ```elixir
-Algolia.list_indexes()
+Algolia.list_indexes(client)
 ```
 
 #### Move an index
 
 ```elixir
-Algolia.move_index(source_index, destination_index)
+Algolia.move_index(client, source_index, destination_index)
 ```
 
 #### Copy an index
 
 ```elixir
-Algolia.copy_index(source_index, destination_index)
+Algolia.copy_index(client, source_index, destination_index)
 ```
 
 #### Clear an index
 
 ```elixir
-Algolia.clear_index(index)
+Algolia.clear_index(client, index)
 ```
 
 ### Settings
 
 #### Get index settings
 
 ```elixir
-Algolia.get_settings(index)
+Algolia.get_settings(client, index)
 ```
 
 Example response:
@@ -238,7 +248,7 @@ Example response:
 #### Update index settings
 
 ```elixir
-Algolia.set_settings(index, %{"hitsPerPage" => 20})
+Algolia.set_settings(client, index, %{"hitsPerPage" => 20})
 
 > {:ok, %{"updatedAt" => "2013-08-21T13:20:18.960Z",
           "taskID" => 10210332.
@@ -250,7 +260,7 @@ Algolia.set_settings(index, %{"hitsPerPage" => 20})
 #### Push events
 
 ```elixir
-Algolia.push_events([
+Algolia.push_events(client, [
   %{
     "eventType" => "click",
     "eventName" => "Product Clicked",