improve documentation for util.ajax and xhr option (#1658)

* improve documentation for util.ajax

* improve xhr documentation

CHANGES.md

@@ -14,6 +14,7 @@ wavesurfer.js changelog
 - Add support for `Blob` output type in `wavesurfer.exportImage` (#1610)
 - Fix fallback to Audio Element in browsers that don't support Web Audio (#1614)
 - `util.getId()` now accepts a `prefix` argument (#1619)
+- Improve documentation for `util.ajax` and `xhr` option (#1656)
 - Fix: the `progressWave` should not be rendered when specifying the same
   value for the `progressColor` and `waveColor` options (#1620)
 - Cursor plugin:

src/util/ajax.js

@@ -3,9 +3,42 @@ import Observer from './observer';
 /**
  * Perform an ajax request
  *
- * @param {Options} options Description
+ * @param {Object} options AJAX options to use. See example below for options.
+ * @returns {Observer} Observer instance
  *
- * @returns {Object} Observer instance
+ * @example
+ * // default options
+ * let options = {
+ *     method: 'GET',
+ *     url: undefined,
+ *     responseType: 'json',
+ *     xhr: {}
+ * };
+ *
+ * // override default options
+ * options.url = '../media/demo.wav';
+ * options.responseType = 'arraybuffer';
+ * options.xhr = {
+ *     requestHeaders: [
+ *         {
+ *             key: 'Authorization',
+ *             value: 'my-token'
+ *         }
+ *     ],
+ *     withCredentials: true
+ * };
+ *
+ * // make ajax call
+ * let ajaxCall = util.ajax(options);
+ * ajaxCall.on('progress', e => {
+ *     console.log('progress', e);
+ * });
+ * ajaxCall.on('success', (data, e) => {
+ *     console.log('success!', data);
+ * });
+ * ajaxCall.on('error', e => {
+ *     console.warn('ajax error: ' + e.target.statusText);
+ * });
  */
 export default function ajax(options) {
     const instance = new Observer();

src/wavesurfer.js

@@ -98,7 +98,16 @@ import PeakCache from './peakcache';
  * the channels of the audio
  * @property {string} waveColor='#999' The fill color of the waveform after the
  * cursor.
- * @property {object} xhr={} XHR options.
+ * @property {object} xhr={} XHR options. For example:
+ * `var xhr = {
+ *     requestHeaders: [
+ *         {
+ *             key: 'Authorization',
+ *             value: 'my-token'
+ *         }
+ *     ],
+ *     withCredentials: true
+ * };`
  */
 
 /**