Added a few examples and a link to the readme, set an ID for the api reference page.

README.md

@@ -33,6 +33,64 @@ We also provide builds of the elasticsearch.js client for use in the browser. If
  - [Extending Core Components](http://elasticsearch.github.io/elasticsearch-js/index.html#extending)
  - [Logging](http://elasticsearch.github.io/elasticsearch-js/index.html#logging)
 
+## Examples
+
+Create a client instance
+```js
+var elasticsearch = require('elasticsearch');
+var client = new elasticsearch.Client({
+  host: 'localhost:9200',
+  log: 'trace'
+});
+```
+
+Send a HEAD request to "/?hello=elasticsearch" and allow up to 1 second for it to complete.
+```js
+client.ping({
+  requestTimeout: 1000,
+  // undocumented params are appended to the query string
+  hello: "elasticsearch!"
+}, function (error) {
+  if (error) {
+    console.trace('elasticsearch cluster is down!');
+  } else {
+    console.log('All is well');
+  }
+});
+```
+
+Skip the callback to get a promise back
+```js
+client.search({
+  q: 'pants'
+}).then(function (body) {
+  var hits = body.hits.hits;
+}, function (error) {
+  console.trace(error.message);
+});
+```
+
+Find tweets that have "elasticsearch" in their body field
+```js
+client.search({
+  index: 'twitter',
+  type: 'tweets',
+  body: {
+    query: {
+      match: {
+        body: 'elasticsearch'
+      }
+    }
+  }
+}).then(function (resp) {
+    var hits = resp.hits.hits;
+}, function (err) {
+    console.trace(err.message);
+});
+```
+
+~~More examples and detailed information about each method are available [here](http://www.elasticsearch.org/guide/en/elasticsearch/client/javascript-api/master/index.html)~~
+
 ## License
 
 This software is licensed under the Apache 2 license, quoted below.

docs/api_methods.asciidoc

@@ -1,3 +1,4 @@
+[[api-reference]]
 == API Method Reference
 
 
@@ -136,6 +137,8 @@ client.cluster.nodeHotThreads([params, [callback]])
 
 Returns information about the hottest threads in the cluster or on a specific node as a String. The information is returned as text, and allows you to understand what are currently the most taxing operations happening in the cluster, for debugging or monitoring purposes.
 
+WARNING: This endpoint returns plain text
+
 The default method is `GET` and the usual <<api-conventions,params and return values>> apply. See http://www.elasticsearch.org/guide/reference/api/admin-cluster-nodes-hot-threads/[the elasticsearch docs] for more about this method.
 
 .Return 10 hottest threads
@@ -143,8 +146,10 @@ The default method is `GET` and the usual <<api-conventions,params and return va
 ---------
 client.cluster.nodeHotThreads({
   threads: 10
+  nodeId: 'mymisbehavingnode',
+  maxRetries: 10
 }, function (error, response) {
-  // WARNING: response is plain text
+  console.log(response);
 })
 ---------
 

docs/quick_start.asciidoc

@@ -48,7 +48,7 @@ client.search({
 }).then(function (body) {
   var hits = body.hits.hits;
 }, function (error) {
-  // freak out!
+  console.trace(error.message);
 });
 -----------------
 
@@ -84,10 +84,9 @@ Now for some examples using the Query DSL.
 
 ===== Simple match query
 
+.Find tweets that have "elasticsearch" in their body field
 [source,js]
 -----------------
-// match tweets that have "elasticsearch"
-// in their body field
 client.search({
   index: 'twitter',
   type: 'tweets',
@@ -98,6 +97,10 @@ client.search({
       }
     }
   }
+}).then(function (resp) {
+    var hits = resp.hits.hits;
+}, function (err) {
+    console.trace(err.message);
 });
 -----------------
 

scripts/generate/templates/api_methods.tmpl

@@ -1,3 +1,4 @@
+[[api-reference]]
 == API Method Reference
 <%
 _.each(actions, function (action) {