Update jsdoc on Libhoney constructor, add esdoc generation to .travis (…

…#12)

* Update jsdoc on Libhoney constructor, add esdoc generation to .travis.yml

* Update README to use es6 style imports

.travis.yml

@@ -1,3 +1,5 @@
 language: node_js
 node_js:
   - "6"
+after_script:
+  - curl 'https://doc.esdoc.org/api/create' -X POST --data-urlencode "gitUrl=git@github.com:honeycombio/libhoney-js.git"

README.md

@@ -12,16 +12,16 @@ npm install libhoney --save-dev
 
 ## Documentation
 
-An API reference is available at https://honeycombio.github.io/libhoney-js/
+An API reference is available at https://doc.esdoc.org/github.com/honeycombio/libhoney-js/
 
 ## Example
 
 Honeycomb can calculate all sorts of statistics, so send the values you care about and let us crunch the averages, percentiles, lower/upper bounds, cardinality -- whatever you want -- for you.
 
 ```js
-var libhoney = require('libhoney').default;
+import Libhoney from 'libhoney';
 
-var hny = new libhoney({
+let hny = new Libhoney({
   writeKey: "YOUR_WRITE_KEY",
   dataset: "honeycomb-js-example"
 });

package.json

@@ -35,7 +35,8 @@
     "gulp-replace": "^0.5.4",
     "jsdoc": "^3.4.0",
     "mocha": "^3.0.2",
-    "superagent-mocker": "^0.5.2"
+    "superagent-mocker": "^0.5.2",
+    "esdoc": "^0.5.2"
   },
   "dependencies": {
     "superagent": "^2.3.0",

src/libhoney.js

@@ -11,7 +11,6 @@ import Builder from './builder';
 import { EventEmitter } from 'events';
 
 const defaults = Object.freeze({
-  // host to send data to
   apiHost: "https://api.honeycomb.io/",
 
   // sample rate of data.  causes us to send 1/sample-rate of events
@@ -30,30 +29,46 @@ const defaults = Object.freeze({
   // to increase parallelism while sending.
   maxConcurrentBatches: 10,
 
-  // the maximum number of pending events we allow in our queue before they get batched
+  // the maximum number of pending events we allow in our to-be-batched-and-transmitted queue before dropping them.
   pendingWorkCapacity: 10000,
 
-  // the maximum number of events we enqueue before we begin dropping them.
+  // the maximum number of responses we enqueue before we begin dropping them.
   maxResponseQueueSize: 1000,
 
   // if this is set to true, all sending is disabled.  useful for disabling libhoney when testing
   disabled: false
 });
 
 /**
- * Represents a honeycomb context.  Each honeycomb context has
+ * libhoney aims to make it as easy as possible to create events and send them on into Honeycomb.
+ *
+ * See https://honeycomb.io/docs for background on this library.
  * @class
  */
 export default class Libhoney extends EventEmitter {
   /**
-   * constructs a libhoney context.
+   * Constructs a libhoney context in order to configure default behavior,
+   * though each of its members (`apiHost`, `writeKey`, `dataset`, and
+   * `sampleRate`) may in fact be overridden on a specific Builder or Event.
    *
    * @param {Object} [opts] overrides for the defaults
+   * @param {string} [opts.apiHost=https://api.honeycomb.io] - Server host to receive Honeycomb events.
+   * @param {string} opts.writeKey - Write key for your Honeycomb team. (Required)
+   * @param {string} opts.dataset - Name of the dataset that should contain this event. The dataset will be created for your team if it doesn't already exist.
+   * @param {number} [opts.sampleRate=1] - Sample rate of data. If set, causes us to send 1/sampleRate of events and drop the rest.
+   * @param {number} [opts.batchSizeTrigger=50] - We send a batch to the API when this many outstanding events exist in our event queue.
+   * @param {number} [opts.batchTimeTrigger=100] - We send a batch to the API after this many milliseconds have passed.
+   * @param {number} [opts.maxConcurrentBatches=10] - We process batches concurrently to increase parallelism while sending.
+   * @param {number} [opts.pendingWorkCapacity=10000] - The maximum number of pending events we allow to accumulate in our sending queue before dropping them.
+   * @param {number} [opts.maxResponseQueueSize=1000] - The maximum number of responses we enqueue before dropping them.
+   * @param {boolean} [opts.disabled=false] - Disable transmission of events to the specified `apiHost`, particularly useful for testing or development.
    * @constructor
    * @example
    * import Libhoney from 'libhoney';
    * let honey = new Libhoney({
-   *   sampleRate: 10
+   *   writeKey: "YOUR_WRITE_KEY",
+   *   dataset: "honeycomb-js-example",
+   *   // disabled: true // uncomment when testing or in development
    * });
    */
   constructor (opts) {