Reference docs improvements for clojurewerkz.elastisch.native.document

src/clojurewerkz/elastisch/native/document.clj

@@ -12,7 +12,31 @@
 
 (defn ^IPersistentMap create
   "Adds document to the search index and waits for the response.
-   If not given as an option, document id will be generated automatically."
+   If not given as an option, document id will be generated automatically.
+
+   Options:
+
+     * :id (string): unique document id. If not provided, it will be generated by ElasticSearch
+     * :timestamp (string): document timestamp either as millis since the epoch,
+                                          or, in the configured date format
+     * :ttl (long): document TTL in milliseconds. Must be > 0
+     * :refresh (boolean, default: false): should a refresh be executed post this index operation?
+     * :version (long): document version
+     * :version-type (string, default: \"internal\"): \"internal\" or \"external\"
+     * :content-type (string): document content type
+     * :routing (string): controls the shard routing of the request. Using this value to hash the shard
+                          and not the id
+     * :percolate (string): the percolate query to use to reduce the percolated queries that are going to run against this doc.
+                           Can be set to \"*\" which means \"all queries\"
+     * :parent (string): parent document id
+
+   Examples:
+
+   (require '[clojurewerkz.elastisch.native.document :as doc])
+
+   (doc/create \"people\" \"person\" {:first-name \"John\" :last-name \"Appleseed\" :age 28})
+
+   (doc/create \"people\" \"person\" {:first-name \"John\" :last-name \"Appleseed\" :age 28} :id \"1825c5432775b8d1a477acfae57e91ac8c767aed\")"
   ([index mapping-type document]
      (let [res (es/index (cnv/->index-request index
                                               mapping-type
@@ -28,8 +52,7 @@
 
 (defn async-create
   "Adds document to the search index and returns a future without waiting
-    for the response.
-   If not given as an option, document id will be generated automatically."
+    for the response. Takes exactly the same arguments as create."
   ([index mapping-type document]
      (future (create index mapping-type document)))
   ([index mapping-type document & {:as params}]
@@ -53,7 +76,7 @@
 
 (defn async-put
   "Creates or updates a document in the search index using the provided document id
-   and returns a future without waiting for the response."
+   and returns a future without waiting for the response. Takes exactly the same arguments as put."
   ([index mapping-type id document]
      (future (put index mapping-type id document)))
   ([index mapping-type id document & {:as params}]
@@ -63,7 +86,13 @@
 
 (defn get
   "Fetches and returns a document by id or nil if it does not exist.
-   Waits for response."
+   Waits for response.
+
+   Examples:
+
+   (require '[clojurewerkz.elastisch.native.document :as doc])
+
+   (doc/get \"people\" \"person\" \"1825c5432775b8d1a477acfae57e91ac8c767aed\")"
   ([index mapping-type id]
      (let [ft               (es/get (cnv/->get-request index
                                                        mapping-type
@@ -103,7 +132,7 @@
    (doc/multi-get [{:_index index-name :_type mapping-type :_id \"1\"}
                    {:_index index-name :_type mapping-type :_id \"2\"}])
 
-   
+
    2-argument version accepts an index name that eliminates the need to include
    :_index in every query map:
 
@@ -136,7 +165,13 @@
        (filter :exists results))))
 
 (defn delete
-  "Deletes document from the index."
+  "Deletes document from the index.
+
+   Examples:
+
+   (require '[clojurewerkz.elastisch.native.document :as doc])
+
+   (doc/delete \"people\" \"person\" \"1825c5432775b8d1a477acfae57e91ac8c767aed\")"
   ([index mapping-type id]
      (let [ft                  (es/delete (cnv/->delete-request index mapping-type id))
            ^DeleteResponse res (.get ft)]
@@ -147,7 +182,14 @@
        (cnv/delete-response->map res))))
 
 (defn delete-by-query
-  "Performs a delete-by-query operation."
+  "Performs a delete-by-query operation.
+
+   Examples:
+
+   (require '[clojurewerkz.elastisch.native.document :as doc])
+   (require '[clojurewerkz.elastisch.query :as q])
+
+   (doc/delete-by-query \"people\" \"person\" (q/term :username \"appleseed\"))"
   ([index mapping-type query]
      (let [ft                         (es/delete-by-query (cnv/->delete-by-query-request index mapping-type query))
            ^DeleteByQueryResponse res (.get ft)]
@@ -181,7 +223,15 @@
        (cnv/delete-by-query-response->map res))))
 
 (defn count
-  "Performs a count query."
+  "Performs a count query.
+
+   Examples:
+
+   (require '[clojurewerkz.elastisch.native.document :as doc])
+   (require '[clojurewerkz.elastisch.query :as q])
+
+   (doc/count \"people\" \"person\")
+   (doc/count \"people\" \"person\" (q/prefix :username \"appl\"))"
   ([index mapping-type]
      (count index mapping-type (q/match-all)))
   ([index mapping-type query]
@@ -199,7 +249,12 @@
 (defn search
   "Performs a search query across one or more indexes and one or more mapping types.
 
-   Passing index name as \"_all\" means searching across all indexes."
+   Examples:
+
+   (require '[clojurewerkz.elastisch.native.document :as doc])
+   (require '[clojurewerkz.elastisch.query :as q])
+
+   (doc/search \"people\" \"person\" :query (q/prefix :username \"appl\"))"
   [index mapping-type & {:as options}]
   (let [ft                  (es/search (cnv/->search-request index mapping-type options))
         ^SearchResponse res (.get ft)]