highcharts 6.1.1 → 6.2.0

package/es-modules/parts/Utilities.js

@@ -1,10 +1,304 @@
 /**
- * (c) 2010-2017 Torstein Honsi
+ * (c) 2010-2018 Torstein Honsi
  *
  * License: www.highcharts.com/license
  */
 
+/**
+ * Reference to the global SVGElement class as a workaround for a name conflict
+ * in the Highcharts namespace.
+ *
+ * @typedef {global.SVGElement} GlobalSVGElement
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/SVGElement
+ */
+
+/**
+ * An animation configuration. Animation configurations can also be defined as
+ * booleans, where `false` turns off animation and `true` defaults to a duration
+ * of 500ms.
+ *
+ * @typedef Highcharts.AnimationOptionsObject
+ *
+ * @property {number} duration
+ *           The animation duration in milliseconds.
+ *
+ * @property {string} [easing]
+ *           The name of an easing function as defined on the `Math` object.
+ *
+ * @property {Function} [complete]
+ *           A callback function to exectute when the animation finishes.
+ *
+ * @property {Function} [step]
+ *           A callback function to execute on each step of each attribute or
+ *           CSS property that's being animated. The first argument contains
+ *           information about the animation and progress.
+ */
+
+/**
+ * A style object with camel case property names to define visual appearance of
+ * a SVG element or HTML element. The properties can be whatever styles are
+ * supported on the given SVG or HTML element.
+ *
+ * @example
+ * {
+ *    fontFamily: 'monospace',
+ *    fontSize: '1.2em'
+ * }
+ *
+ * @typedef Highcharts.CSSObject
+ *
+ * @property {boolean|number|string|undefined} [key:string]
+ *
+ * @property {string} [background]
+ *           Background style for the element.
+ *
+ * @property {Highcharts.ColorString} [backgroundColor]
+ *           Background color of the element.
+ *
+ * @property {string} [border]
+ *           Border style for the element.
+ *
+ * @property {number} [borderRadius]
+ *           Radius of the element border.
+ *
+ * @property {"contrast"|Highcharts.ColorString} [color]
+ *           Color used in the element. The "contrast" option is a Highcharts
+ *           custom property that results in black or white, depending on the
+ *           background of the element.
+ *
+ * @property {string} [cursor]
+ *           Style of the mouse cursor when resting over the element.
+ *
+ * @property {string} [fontFamily]
+ *           Font family of the element text. Multiple values have to be in
+ *           decreasing preference order and separated by comma.
+ *
+ * @property {string} [fontSize]
+ *           Font size of the element text.
+ *
+ * @property {string} [fontWeight]
+ *           Font weight of the element text.
+ *
+ * @property {number} [height]
+ *           Height of the element.
+ *
+ * @property {number} [lineWidth]
+ *           Width of the element border.
+ *
+ * @property {number} [opacity]
+ *           Opacity of the element.
+ *
+ * @property {string} [padding]
+ *           Space around the element content.
+ *
+ * @property {string} [pointerEvents]
+ *           Behaviour of the element when the mouse cursor rests over it.
+ *
+ * @property {string} [position]
+ *           Positioning of the element.
+ *
+ * @property {string} [textAlign]
+ *           Alignment of the element text.
+ *
+ * @property {string} [textOutline]
+ *           Outline style of the element text.
+ *
+ * @property {string} [textDecoration]
+ *           Additional decoration of the element text.
+ *
+ * @property {string} [textOverflow]
+ *           Line break style of the element text. Highcharts SVG elements
+ *           support `ellipsis` when a `width` is set.
+ *
+ * @property {string} [transition]
+ *           Animated transition of selected element properties.
+ *
+ * @property {string} [top]
+ *           Top spacing of the element relative to the parent element.
+ *
+ * @property {string} [whiteSpace]
+ *           Line break style of the element text.
+ *
+ * @property {number} [width]
+ *           Width of the element.
+ */
+
+/**
+ * Generic dictionary in TypeScript notation.
+ *
+ * @typedef Highcharts.Dictionary<T>
+ *
+ * @property {T} [key:string]
+ */
+
+/**
+ * An object of key-value pairs for HTML attributes.
+ *
+ * @typedef {Highcharts.Dictionary<boolean|number|string>} Highcharts.HTMLAttributes
+ */
+
+/**
+ * The iterator callback.
+ *
+ * @callback Highcharts.EachCallbackFunction<T>
+ *
+ * @param {T} item
+ *        The array item.
+ *
+ * @param {number} index
+ *        The item's index in the array.
+ *
+ * @param {Array<T>} arr
+ *        The array that each is being applied to.
+ */
+
+/**
+ * The function callback to execute when the event is fired. The `this` context
+ * contains the instance, that fired the event.
+ *
+ * @callback Highcharts.EventCallbackFunction
+ *
+ * @param {Highcharts.Dictionary<*>} [eventArguments]
+ *        Event arguments.
+ */
+
+/**
+ * Formats data as a string. Usually the data is accessible throught the `this`
+ * keyword.
+ *
+ * @callback Highcharts.FormatterCallbackFunction
+ *
+ * @return {string}
+ */
+
+/**
+ * An HTML DOM element. The type is a reference to the regular SVGElement in the
+ * global scope.
+ *
+ * @typedef {global.HTMLElement} Highcharts.HTMLDOMElement
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement
+ */
+
+/**
+ * The iterator callback.
+ *
+ * @callback Highcharts.ObjectEachCallbackFunction
+ *
+ * @param {*} value
+ *        The property value.
+ *
+ * @param {string} key
+ *        The property key.
+ *
+ * @param {*} obj
+ *        The object that objectEach is being applied to.
+ */
+
+/**
+ * An object containing `left` and `top` properties for the position in the
+ * page.
+ *
+ * @typedef Highcharts.OffsetObject
+ *
+ * @property {number} left
+ *           Left distance to the page border.
+ *
+ * @property {number} top
+ *           Top distance to the page border.
+ */
+
+/**
+ * An object containing `x` and `y` properties for the position of an element.
+ *
+ * @typedef Highcharts.PositionObject
+ *
+ * @property {number} x
+ *           X position of the element.
+ *
+ * @property {number} y
+ *           Y position of the element.
+ */
+
+/**
+ * If a number is given, it defines the pixel length. If a percentage string is
+ * given, like for example `'50%'`, the setting defines a length relative to a
+ * base size, for example the size of a container.
+ *
+ * @typedef {number|string} Highcharts.RelativeSize
+ */
+
+/**
+ * An object of key-value pairs for SVG attributes. Attributes in Highcharts
+ * elements for the most parts correspond to SVG, but some are specific to
+ * Highcharts, like `zIndex`, `rotation`, `rotationOriginX`,
+ * `rotationOriginY`, `translateX`, `translateY`, `scaleX` and `scaleY`. SVG
+ * attributes containing a hyphen are _not_ camel-cased, they should be
+ * quoted to preserve the hyphen.
+ *
+ * @example
+ * {
+ *     'stroke': '#ff0000', // basic
+ *     'stroke-width': 2, // hyphenated
+ *     'rotation': 45 // custom
+ *     'd': ['M', 10, 10, 'L', 30, 30, 'z'] // path definition, note format
+ * }
+ *
+ * @typedef Highcharts.SVGAttributes
+ *
+ * @property {boolean|number|string|Array<any>|undefined} [key:string]
+ *
+ * @property {string|Highcharts.SVGPathArray} [d]
+ *
+ * @property {boolean} [inverted]
+ *
+ * @property {Array<number>} [matrix]
+ *
+ * @property {Highcharts.ColorString} [stroke]
+ *
+ * @property {string} [rotation]
+ *
+ * @property {number} [rotationOriginX]
+ *
+ * @property {number} [rotationOriginY]
+ *
+ * @property {number} [scaleX]
+ *
+ * @property {number} [scaleY]
+ *
+ * @property {number} [translateX]
+ *
+ * @property {number} [translateY]
+ *
+ * @property {number} [zIndex]
+ */
+
+/**
+ * An SVG DOM element. The type is a reference to the regular SVGElement in the
+ * global scope.
+ *
+ * @typedef {global.GlobalSVGElement} Highcharts.SVGDOMElement
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/API/SVGElement
+ */
+
+/**
+ * Array of path commands, that will go into the `d` attribute of an SVG
+ * element.
+ *
+ * @typedef {Array<number|Highcharts.SVGPathCommand>} Highcharts.SVGPathArray
+ */
+
+/**
+ * Possible path commands in a SVG path array.
+ *
+ * @typedef {string} Highcharts.SVGPathCommand
+ * @validvalue ["a","c","h","l","m","q","s","t","v","z","A","C","H","L","M","Q","S","T","V","Z"]
+ */
+
 'use strict';
+
 import H from './Globals.js';
 
 /**
@@ -28,16 +322,19 @@ var charts = H.charts,
  * Provide error messages for debugging, with links to online explanation. This
  * function can be overridden to provide custom error handling.
  *
- * @function #error
- * @memberof Highcharts
- * @param {Number|String} code - The error code. See [errors.xml]{@link
- *     https://github.com/highcharts/highcharts/blob/master/errors/errors.xml}
- *     for available codes. If it is a string, the error message is printed
- *     directly in the console.
- * @param {Boolean} [stop=false] - Whether to throw an error or just log a
- *     warning in the console.
+ * @sample highcharts/chart/highcharts-error/
+ *         Custom error handler
+ *
+ * @function Highcharts.error
  *
- * @sample highcharts/chart/highcharts-error/ Custom error handler
+ * @param {number|string} code
+ *        The error code. See
+ *        [errors.xml]{@link https://github.com/highcharts/highcharts/blob/master/errors/errors.xml}
+ *        for available codes. If it is a string, the error message is printed
+ *        directly in the console.
+ *
+ * @param {boolean} [stop=false]
+ *        Whether to throw an error or just log a warning in the console.
  */
 H.error = function (code, stop) {
     var msg = H.isNumber(code) ?
@@ -57,16 +354,21 @@ H.error = function (code, stop) {
  * (attribute or style prop) on one element. Animation is always initiated
  * through {@link SVGElement#animate}.
  *
- * @constructor Fx
- * @memberof Highcharts
- * @param {HTMLDOMElement|SVGElement} elem - The element to animate.
- * @param {AnimationOptions} options - Animation options.
- * @param {string} prop - The single attribute or CSS property to animate.
- * @private
- *
  * @example
  * var rect = renderer.rect(0, 0, 10, 10).add();
  * rect.animate({ width: 100 });
+ *
+ * @private
+ * @class Highcharts.Fx
+ *
+ * @param {Highcharts.HTMLDOMElement|Highcharts.SVGElement} elem
+ *        The element to animate.
+ *
+ * @param {Highcharts.AnimationOptionsObject} options
+ *        Animation options.
+ *
+ * @param {string} prop
+ *        The single attribute or CSS property to animate.
  */
 H.Fx = function (elem, options, prop) {
     this.options = options;
@@ -78,8 +380,7 @@ H.Fx.prototype = {
     /**
      * Set the current step of a path definition on SVGElement.
      *
-     * @function #dSetter
-     * @memberof Highcharts.Fx
+     * @function Highcharts.Fx#dSetter
      */
     dSetter: function () {
         var start = this.paths[0],
@@ -112,8 +413,7 @@ H.Fx.prototype = {
     /**
      * Update the element with the current animation step.
      *
-     * @function #update
-     * @memberof Highcharts.Fx
+     * @function Highcharts.Fx#update
      */
     update: function () {
         var elem = this.elem,
@@ -145,12 +445,16 @@ H.Fx.prototype = {
     /**
      * Run an animation.
      *
-     * @function #run
-     * @memberof Highcharts.Fx
-     * @param {Number} from - The current value, value to start from.
-     * @param {Number} to - The end value, value to land on.
-     * @param {String} [unit] - The property unit, for example `px`.
+     * @function Highcharts.Fx#run
+     *
+     * @param {number} from
+     *        The current value, value to start from.
      *
+     * @param {number} to
+     *        The end value, value to land on.
+     *
+     * @param {string} [unit]
+     *        The property unit, for example `px`.
      */
     run: function (from, to, unit) {
         var self = this,
@@ -200,11 +504,13 @@ H.Fx.prototype = {
     /**
      * Run a single step in the animation.
      *
-     * @function #step
-     * @memberof Highcharts.Fx
-     * @param   {Boolean} [gotoEnd] - Whether to go to the endpoint of the
-     *     animation after abort.
-     * @returns {Boolean} Returns `true` if animation continues.
+     * @function Highcharts.Fx#step
+     *
+     * @param {boolean} [gotoEnd]
+     *        Whether to go to the endpoint of the animation after abort.
+     *
+     * @return {boolean}
+     *         Returns `true` if animation continues.
      */
     step: function (gotoEnd) {
         var t = +new Date(),
@@ -251,13 +557,20 @@ H.Fx.prototype = {
     /**
      * Prepare start and end values so that the path can be animated one to one.
      *
-     * @function #initPath
-     * @memberof Highcharts.Fx
-     * @param {SVGElement} elem - The SVGElement item.
-     * @param {String} fromD - Starting path definition.
-     * @param {Array} toD - Ending path definition.
-     * @returns {Array} An array containing start and end paths in array form
-     * so that they can be animated in parallel.
+     * @function Highcharts.Fx#initPath
+     *
+     * @param {Highcharts.SVGElement} elem
+     *        The SVGElement item.
+     *
+     * @param {string} fromD
+     *        Starting path definition.
+     *
+     * @param {Highcharts.SVGPathArray} toD
+     *        Ending path definition.
+     *
+     * @return {Array<Highcharts.SVGPathArray>}
+     *         An array containing start and end paths in array form so that
+     *         they can be animated in parallel.
      */
     initPath: function (elem, fromD, toD) {
         fromD = fromD || '';
@@ -335,7 +648,7 @@ H.Fx.prototype = {
         }
 
         /**
-         * Copy and append last point until the length matches the end length
+         * Copy and append last point until the length matches the end length.
          */
         function append(arr, other) {
             var i = (fullLength - arr.length) / numParams;
@@ -413,38 +726,74 @@ H.Fx.prototype = {
         }
 
         return [start, end];
+    },
+
+    /**
+     * Handle animation of the color attributes directly.
+     *
+     * @function Highcharts.Fx#fillSetter
+     */
+    fillSetter: function () {
+        H.Fx.prototype.strokeSetter.apply(this, arguments);
+    },
+
+    /**
+     * Handle animation of the color attributes directly.
+     *
+     * @function Highcharts.Fx#strokeSetter
+     */
+    strokeSetter: function () {
+        this.elem.attr(
+            this.prop,
+            H.color(this.start).tweenTo(H.color(this.end), this.pos),
+            null,
+            true
+        );
     }
+
 }; // End of Fx prototype
 
-/**
- * Handle animation of the color attributes directly.
- */
-H.Fx.prototype.fillSetter =
-H.Fx.prototype.strokeSetter = function () {
-    this.elem.attr(
-        this.prop,
-        H.color(this.start).tweenTo(H.color(this.end), this.pos),
-        null,
-        true
-    );
-};
 
 
 /**
+ * Utility function to deep merge two or more objects and return a third object.
+ * The merge function can also be used with a single object argument to create a
+ * deep copy of an object.
+ *
+ * @function Highcharts.merge
+ *
+ * @param {*} a
+ *        The first object to extend. When only this is given, the function
+ *        returns a deep copy.
+ *
+ * @param {*} [n]
+ *        An object to merge into the previous one.
+ *
+ * @return {*}
+ *         The merged object. If the first argument is true, the return is the
+ *         same as the second argument.
+ *//**
  * Utility function to deep merge two or more objects and return a third object.
  * If the first argument is true, the contents of the second object is copied
  * into the first object. The merge function can also be used with a single
  * object argument to create a deep copy of an object.
  *
- * @function #merge
- * @memberof Highcharts
- * @param {Boolean} [extend] - Whether to extend the left-side object (a) or
-          return a whole new object.
- * @param {Object} a - The first object to extend. When only this is given, the
-          function returns a deep copy.
- * @param {...Object} [n] - An object to merge into the previous one.
- * @returns {Object} - The merged object. If the first argument is true, the
- * return is the same as the second argument.
+ * @function Highcharts.merge
+ *
+ * @param {boolean} extend
+ *        Whether to extend the left-side object (a) or return a whole new
+ *        object.
+ *
+ * @param {*} a
+ *        The first object to extend. When only this is given, the function
+ *        returns a deep copy.
+ *
+ * @param {*} [n]
+ *        An object to merge into the previous one.
+ *
+ * @return {*}
+ *         The merged object. If the first argument is true, the return is the
+ *         same as the second argument.
  */
 H.merge = function () {
     var i,
@@ -493,9 +842,16 @@ H.merge = function () {
 
 /**
  * Shortcut for parseInt
- * @ignore
- * @param {Object} s
- * @param {Number} mag Magnitude
+ *
+ * @private
+ * @function Highcharts.pInt
+ *
+ * @param {*} s
+ *
+ * @param {number} mag
+ *        Magnitude
+ *
+ * @return {number}
  */
 H.pInt = function (s, mag) {
     return parseInt(s, mag || 10);
@@ -504,10 +860,13 @@ H.pInt = function (s, mag) {
 /**
  * Utility function to check for string type.
  *
- * @function #isString
- * @memberof Highcharts
- * @param {Object} s - The item to check.
- * @returns {Boolean} - True if the argument is a string.
+ * @function Highcharts.isString
+ *
+ * @param {*} s
+ *        The item to check.
+ *
+ * @return {boolean}
+ *         True if the argument is a string.
  */
 H.isString = function (s) {
     return typeof s === 'string';
@@ -516,10 +875,13 @@ H.isString = function (s) {
 /**
  * Utility function to check if an item is an array.
  *
- * @function #isArray
- * @memberof Highcharts
- * @param {Object} obj - The item to check.
- * @returns {Boolean} - True if the argument is an array.
+ * @function Highcharts.isArray
+ *
+ * @param {*} obj
+ *        The item to check.
+ *
+ * @return {boolean}
+ *         True if the argument is an array.
  */
 H.isArray = function (obj) {
     var str = Object.prototype.toString.call(obj);
@@ -529,12 +891,16 @@ H.isArray = function (obj) {
 /**
  * Utility function to check if an item is of type object.
  *
- * @function #isObject
- * @memberof Highcharts
- * @param {Object} obj - The item to check.
- * @param {Boolean} [strict=false] - Also checks that the object is not an
- *    array.
- * @returns {Boolean} - True if the argument is an object.
+ * @function Highcharts.isObject
+ *
+ * @param {*} obj
+ *        The item to check.
+ *
+ * @param {boolean} [strict=false]
+ *        Also checks that the object is not an array.
+ *
+ * @return {boolean}
+ *         True if the argument is an object.
  */
 H.isObject = function (obj, strict) {
     return !!obj && typeof obj === 'object' && (!strict || !H.isArray(obj));
@@ -543,10 +909,13 @@ H.isObject = function (obj, strict) {
 /**
  * Utility function to check if an Object is a HTML Element.
  *
- * @function #isDOMElement
- * @memberof Highcharts
- * @param {Object} obj - The item to check.
- * @returns {Boolean} - True if the argument is a HTML Element.
+ * @function Highcharts.isDOMElement
+ *
+ * @param {*} obj
+ *        The item to check.
+ *
+ * @return {boolean}
+ *         True if the argument is a HTML Element.
  */
 H.isDOMElement = function (obj) {
     return H.isObject(obj) && typeof obj.nodeType === 'number';
@@ -555,10 +924,13 @@ H.isDOMElement = function (obj) {
 /**
  * Utility function to check if an Object is an class.
  *
- * @function #isClass
- * @memberof Highcharts
- * @param {Object} obj - The item to check.
- * @returns {Boolean} - True if the argument is an class.
+ * @function Highcharts.isClass
+ *
+ * @param {*} obj
+ *        The item to check.
+ *
+ * @return {boolean}
+ *         True if the argument is an class.
  */
 H.isClass = function (obj) {
     var c = obj && obj.constructor;
@@ -573,11 +945,12 @@ H.isClass = function (obj) {
  * Utility function to check if an item is a number and it is finite (not NaN,
  * Infinity or -Infinity).
  *
- * @function #isNumber
- * @memberof Highcharts
- * @param  {Object} n
- *         The item to check.
- * @return {Boolean}
+ * @function Highcharts.isNumber
+ *
+ * @param {*} n
+ *        The item to check.
+ *
+ * @return {boolean}
  *         True if the item is a finite number
  */
 H.isNumber = function (n) {
@@ -587,10 +960,13 @@ H.isNumber = function (n) {
 /**
  * Remove the last occurence of an item from an array.
  *
- * @function #erase
- * @memberof Highcharts
- * @param {Array} arr - The array.
- * @param {*} item - The item to remove.
+ * @function Highcharts.erase
+ *
+ * @param {Array} arr
+ *        The array.
+ *
+ * @param {*} item
+ *        The item to remove.
  */
 H.erase = function (arr, item) {
     var i = arr.length;
@@ -605,11 +981,13 @@ H.erase = function (arr, item) {
 /**
  * Check if an object is null or undefined.
  *
- * @function #defined
- * @memberof Highcharts
- * @param {Object} obj - The object to check.
- * @returns {Boolean} - False if the object is null or undefined, otherwise
- *        true.
+ * @function Highcharts.defined
+ *
+ * @param {*} obj
+ *        The object to check.
+ *
+ * @return {boolean}
+ *         False if the object is null or undefined, otherwise true.
  */
 H.defined = function (obj) {
     return obj !== undefined && obj !== null;
@@ -620,12 +998,19 @@ H.defined = function (obj) {
  * a key and a value, or let the second argument be a collection of keys and
  * values. To use as a getter, pass only a string as the second argument.
  *
- * @function #attr
- * @memberof Highcharts
- * @param {Object} elem - The DOM element to receive the attribute(s).
- * @param {String|Object} [prop] - The property or an object of key-value pairs.
- * @param {String} [value] - The value if a single property is set.
- * @returns {*} When used as a getter, return the value.
+ * @function Highcharts.attr
+ *
+ * @param {Highcharts.HTMLDOMElement|Highcharts.SVGDOMElement} elem
+ *        The DOM element to receive the attribute(s).
+ *
+ * @param {string|Highcharts.HTMLAttributes|Highcharts.SVGAttributes} [prop]
+ *        The property or an object of key-value pairs.
+ *
+ * @param {string} [value]
+ *        The value if a single property is set.
+ *
+ * @return {*}
+ *         When used as a getter, return the value.
  */
 H.attr = function (elem, prop, value) {
     var ret;
@@ -658,10 +1043,13 @@ H.attr = function (elem, prop, value) {
 /**
  * Check if an element is an array, and if not, make it into an array.
  *
- * @function #splat
- * @memberof Highcharts
- * @param obj {*} - The object to splat.
- * @returns {Array} The produced or original array.
+ * @function Highcharts.splat
+ *
+ * @param {*} obj
+ *        The object to splat.
+ *
+ * @return {Array}
+ *         The produced or original array.
  */
 H.splat = function (obj) {
     return H.isArray(obj) ? obj : [obj];
@@ -671,13 +1059,20 @@ H.splat = function (obj) {
  * Set a timeout if the delay is given, otherwise perform the function
  * synchronously.
  *
- * @function #syncTimeout
- * @memberof Highcharts
- * @param   {Function} fn - The function callback.
- * @param   {Number}   delay - Delay in milliseconds.
- * @param   {Object}   [context] - The context.
- * @returns {Number} An identifier for the timeout that can later be cleared
- * with H.clearTimeout.
+ * @function Highcharts.syncTimeout
+ *
+ * @param {Function} fn
+ *        The function callback.
+ *
+ * @param {number} delay
+ *        Delay in milliseconds.
+ *
+ * @param {*} [context]
+ *        The context.
+ *
+ * @return {number}
+ *         An identifier for the timeout that can later be cleared with
+ *         Highcharts.clearTimeout.
  */
 H.syncTimeout = function (fn, delay, context) {
     if (delay) {
@@ -691,9 +1086,10 @@ H.syncTimeout = function (fn, delay, context) {
  * (e.g. by `chart.destroy()`). For the details see
  * [issue #7901](https://github.com/highcharts/highcharts/issues/7901).
  *
- * @function #clearTimeout
- * @memberof Highcharts
- * @param   {Number}   id - id of a timeout.
+ * @function Highcharts.clearTimeout
+ *
+ * @param {number} id
+ *        Id of a timeout.
  */
 H.clearTimeout = function (id) {
     if (H.defined(id)) {
@@ -704,11 +1100,16 @@ H.clearTimeout = function (id) {
 /**
  * Utility function to extend an object with the members of another.
  *
- * @function #extend
- * @memberof Highcharts
- * @param {Object} a - The object to be extended.
- * @param {Object} b - The object to add to the first one.
- * @returns {Object} Object a, the original object.
+ * @function Highcharts.extend
+ *
+ * @param {Highcharts.Dictionary<*>} a
+ *        The object to be extended.
+ *
+ * @param {Highcharts.Dictionary<*>} b
+ *        The object to add to the first one.
+ *
+ * @return {Highcharts.Dictionary<*>}
+ *         Object a, the original object.
  */
 H.extend = function (a, b) {
     var n;
@@ -725,10 +1126,13 @@ H.extend = function (a, b) {
 /**
  * Return the first value that is not null or undefined.
  *
- * @function #pick
- * @memberof Highcharts
- * @param {...*} items - Variable number of arguments to inspect.
- * @returns {*} The value of the first argument that is not null or undefined.
+ * @function Highcharts.pick
+ *
+ * @param {...*} items
+ *        Variable number of arguments to inspect.
+ *
+ * @return {*}
+ *         The value of the first argument that is not null or undefined.
  */
 H.pick = function () {
     var args = arguments,
@@ -743,24 +1147,16 @@ H.pick = function () {
     }
 };
 
-/**
- * @typedef {Object} CSSObject - A style object with camel case property names.
- * The properties can be whatever styles are supported on the given SVG or HTML
- * element.
- * @example
- * {
- *    fontFamily: 'monospace',
- *    fontSize: '1.2em'
- * }
- */
 /**
  * Set CSS on a given element.
  *
- * @function #css
- * @memberof Highcharts
- * @param {HTMLDOMElement} el - A HTML DOM element.
- * @param {CSSObject} styles - Style object with camel case property names.
+ * @function Highcharts.css
  *
+ * @param {Highcharts.HTMLDOMElement} el
+ *        An HTML DOM element.
+ *
+ * @param {Highcharts.CSSObject} styles
+ *        Style object with camel case property names.
  */
 H.css = function (el, styles) {
     if (H.isMS && !H.svg) { // #2686
@@ -771,23 +1167,28 @@ H.css = function (el, styles) {
     H.extend(el.style, styles);
 };
 
-/**
- * A HTML DOM element.
- * @typedef {Object} HTMLDOMElement
- */
-
 /**
  * Utility function to create an HTML element with attributes and styles.
  *
- * @function #createElement
- * @memberof Highcharts
- * @param {String} tag - The HTML tag.
- * @param {Object} [attribs] - Attributes as an object of key-value pairs.
- * @param {CSSObject} [styles] - Styles as an object of key-value pairs.
- * @param {Object} [parent] - The parent HTML object.
- * @param {Boolean} [nopad=false] - If true, remove all padding, border and
- *    margin.
- * @returns {HTMLDOMElement} The created DOM element.
+ * @function Highcharts.createElement
+ *
+ * @param {string} tag
+ *        The HTML tag.
+ *
+ * @param {Highcharts.HTMLAttributes} [attribs]
+ *        Attributes as an object of key-value pairs.
+ *
+ * @param {Highcharts.CSSObject} [styles]
+ *        Styles as an object of key-value pairs.
+ *
+ * @param {Highcharts.HTMLDOMElement} [parent]
+ *        The parent HTML object.
+ *
+ * @param {boolean} [nopad=false]
+ *        If true, remove all padding, border and margin.
+ *
+ * @return {Highcharts.HTMLDOMElement}
+ *         The created DOM element.
  */
 H.createElement = function (tag, attribs, styles, parent, nopad) {
     var el = doc.createElement(tag),
@@ -810,12 +1211,17 @@ H.createElement = function (tag, attribs, styles, parent, nopad) {
 /**
  * Extend a prototyped class by new members.
  *
- * @function #extendClass
- * @memberof Highcharts
- * @param {Object} parent - The parent prototype to inherit.
- * @param {Object} members - A collection of prototype members to add or
- *        override compared to the parent prototype.
- * @returns {Object} A new prototype.
+ * @function Highcharts.extendClass
+ *
+ * @param {*} parent
+ *        The parent prototype to inherit.
+ *
+ * @param {Highcharts.Dictionary<*>} members
+ *        A collection of prototype members to add or override compared to the
+ *        parent prototype.
+ *
+ * @return {*}
+ *         A new prototype.
  */
 H.extendClass = function (parent, members) {
     var object = function () {};
@@ -827,12 +1233,19 @@ H.extendClass = function (parent, members) {
 /**
  * Left-pad a string to a given length by adding a character repetetively.
  *
- * @function #pad
- * @memberof Highcharts
- * @param {Number} number - The input string or number.
- * @param {Number} length - The desired string length.
- * @param {String} [padder=0] - The character to pad with.
- * @returns {String} The padded string.
+ * @function Highcharts.pad
+ *
+ * @param {number} number
+ *        The input string or number.
+ *
+ * @param {number} length
+ *        The desired string length.
+ *
+ * @param {string} [padder=0]
+ *        The character to pad with.
+ *
+ * @return {string}
+ *         The padded string.
  */
 H.pad = function (number, length, padder) {
     return new Array(
@@ -844,24 +1257,21 @@ H.pad = function (number, length, padder) {
         ).join(padder || 0) + number;
 };
 
-/**
- * @typedef {Number|String} RelativeSize - If a number is given, it defines the
- *    pixel length. If a percentage string is given, like for example `'50%'`,
- *    the setting defines a length relative to a base size, for example the size
- *    of a container.
- */
 /**
  * Return a length based on either the integer value, or a percentage of a base.
  *
- * @function #relativeLength
- * @memberof Highcharts
- * @param  {RelativeSize} value
- *         A percentage string or a number.
- * @param  {number} base
- *         The full length that represents 100%.
- * @param  {number} [offset=0]
- *         A pixel offset to apply for percentage values. Used internally in
- *         axis positioning.
+ * @function Highcharts.relativeLength
+ *
+ * @param {Highcharts.RelativeSize} value
+ *        A percentage string or a number.
+ *
+ * @param {number} base
+ *        The full length that represents 100%.
+ *
+ * @param {number} [offset=0]
+ *        A pixel offset to apply for percentage values. Used internally in
+ *        axis positioning.
+ *
  * @return {number}
  *         The computed length.
  */
@@ -874,15 +1284,19 @@ H.relativeLength = function (value, base, offset) {
 /**
  * Wrap a method with extended functionality, preserving the original function.
  *
- * @function #wrap
- * @memberof Highcharts
- * @param {Object} obj - The context object that the method belongs to. In real
- *        cases, this is often a prototype.
- * @param {String} method - The name of the method to extend.
- * @param {Function} func - A wrapper function callback. This function is called
- *        with the same arguments as the original function, except that the
- *        original function is unshifted and passed as the first argument.
+ * @function Highcharts.wrap
  *
+ * @param {*} obj
+ *        The context object that the method belongs to. In real cases, this is
+ *        often a prototype.
+ *
+ * @param {string} method
+ *        The name of the method to extend.
+ *
+ * @param {Function} func
+ *        A wrapper function callback. This function is called with the same
+ *        arguments as the original function, except that the original function
+ *        is unshifted and passed as the first argument.
  */
 H.wrap = function (obj, method, func) {
     var proceed = obj[method];
@@ -903,21 +1317,41 @@ H.wrap = function (obj, method, func) {
 
 
 
+/**
+ * Recursively converts all Date properties to timestamps.
+ *
+ * @param  {Object} object - any object to convert properties of
+ */
+H.datePropsToTimestamps = function (object) {
+    H.objectEach(object, function (val, key) {
+        if (H.isObject(val) && typeof val.getTime === 'function') {
+            object[key] = val.getTime();
+        } else if (H.isObject(val) || H.isArray(val)) {
+            H.datePropsToTimestamps(val);
+        }
+    });
+};
+
 /**
  * Format a single variable. Similar to sprintf, without the % prefix.
  *
  * @example
  * formatSingle('.2f', 5); // => '5.00'.
  *
- * @function #formatSingle
- * @memberof Highcharts
- * @param {String} format The format string.
- * @param {*} val The value.
- * @param {Time}   [time]
- *        A `Time` instance that determines the date formatting, for example for
- *        applying time zone corrections to the formatted date.
-
- * @returns {String} The formatted representation of the value.
+ * @function Highcharts.formatSingle
+ *
+ * @param {string} format
+ *        The format string.
+ *
+ * @param {*} val
+ *        The value.
+ *
+ * @param {Highcharts.Time} [time]
+ *        A `Time` instance that determines the date formatting, for example
+ *        for applying time zone corrections to the formatted date.
+ *
+ * @return {string}
+ *         The formatted representation of the value.
  */
 H.formatSingle = function (format, val, time) {
     var floatRegex = /f$/,
@@ -946,24 +1380,28 @@ H.formatSingle = function (format, val, time) {
  * Format a string according to a subset of the rules of Python's String.format
  * method.
  *
- * @function #format
- * @memberof Highcharts
- * @param {String} str
- *        The string to format.
- * @param {Object} ctx
- *        The context, a collection of key-value pairs where each key is
- *        replaced by its value.
- * @param {Time}   [time]
- *        A `Time` instance that determines the date formatting, for example for
- *        applying time zone corrections to the formatted date.
- * @returns {String} The formatted string.
- *
  * @example
  * var s = Highcharts.format(
  *     'The {color} fox was {len:.2f} feet long',
  *     { color: 'red', len: Math.PI }
  * );
  * // => The red fox was 3.14 feet long
+ *
+ * @function Highcharts.format
+ *
+ * @param {string} str
+ *        The string to format.
+ *
+ * @param {*} ctx
+ *        The context, a collection of key-value pairs where each key is
+ *        replaced by its value.
+ *
+ * @param {Highcharts.Time} [time]
+ *        A `Time` instance that determines the date formatting, for example
+ *        for applying time zone corrections to the formatted date.
+ *
+ * @return {string}
+ *         The formatted string.
  */
 H.format = function (str, ctx, time) {
     var splitter = '{',
@@ -1021,11 +1459,13 @@ H.format = function (str, ctx, time) {
 /**
  * Get the magnitude of a number.
  *
- * @function #getMagnitude
- * @memberof Highcharts
- * @param {Number} number The number.
- * @returns {Number} The magnitude, where 1-9 are magnitude 1, 10-99 magnitude 2
- *        etc.
+ * @function Highcharts.getMagnitude
+ *
+ * @param {number} number
+ *        The number.
+ *
+ * @return {number}
+ *         The magnitude, where 1-9 are magnitude 1, 10-99 magnitude 2 etc.
  */
 H.getMagnitude = function (num) {
     return Math.pow(10, Math.floor(Math.log(num) / Math.LN10));
@@ -1034,17 +1474,31 @@ H.getMagnitude = function (num) {
 /**
  * Take an interval and normalize it to multiples of round numbers.
  *
- * @todo  Move this function to the Axis prototype. It is here only for
- *        historical reasons.
- * @function #normalizeTickInterval
- * @memberof Highcharts
- * @param {Number} interval - The raw, un-rounded interval.
- * @param {Array} [multiples] - Allowed multiples.
- * @param {Number} [magnitude] - The magnitude of the number.
- * @param {Boolean} [allowDecimals] - Whether to allow decimals.
- * @param {Boolean} [hasTickAmount] - If it has tickAmount, avoid landing
- *        on tick intervals lower than original.
- * @returns {Number} The normalized interval.
+ * @deprecated
+ * @function Highcharts.normalizeTickInterval
+ *
+ * @param {number} interval
+ *        The raw, un-rounded interval.
+ *
+ * @param {Array} [multiples]
+ *        Allowed multiples.
+ *
+ * @param {number} [magnitude]
+ *        The magnitude of the number.
+ *
+ * @param {boolean} [allowDecimals]
+ *        Whether to allow decimals.
+ *
+ * @param {boolean} [hasTickAmount]
+ *        If it has tickAmount, avoid landing on tick intervals lower than
+ *        original.
+ *
+ * @return {number}
+ *         The normalized interval.
+ *
+ * @todo
+ * Move this function to the Axis prototype. It is here only for historical
+ * reasons.
  */
 H.normalizeTickInterval = function (interval, multiples, magnitude,
         allowDecimals, hasTickAmount) {
@@ -1118,12 +1572,13 @@ H.normalizeTickInterval = function (interval, multiples, magnitude,
  * Sort an object array and keep the order of equal items. The ECMAScript
  * standard does not specify the behaviour when items are equal.
  *
- * @function #stableSort
- * @memberof Highcharts
- * @param {Array} arr - The array to sort.
- * @param {Function} sortFunction - The function to sort it with, like with
- *        regular Array.prototype.sort.
+ * @function Highcharts.stableSort
+ *
+ * @param {Array} arr
+ *        The array to sort.
  *
+ * @param {Function} sortFunction
+ *        The function to sort it with, like with regular Array.prototype.sort.
  */
 H.stableSort = function (arr, sortFunction) {
     var length = arr.length,
@@ -1151,10 +1606,13 @@ H.stableSort = function (arr, sortFunction) {
  * a maximum call stack size exceeded error in Chrome when trying to apply more
  * than 150.000 points. This method is slightly slower, but safe.
  *
- * @function #arrayMin
- * @memberof Highcharts
- * @param {Array} data An array of numbers.
- * @returns {Number} The lowest number.
+ * @function Highcharts.arrayMin
+ *
+ * @param {Array} data
+ *        An array of numbers.
+ *
+ * @return {number}
+ *         The lowest number.
  */
 H.arrayMin = function (data) {
     var i = data.length,
@@ -1173,10 +1631,13 @@ H.arrayMin = function (data) {
  * a maximum call stack size exceeded error in Chrome when trying to apply more
  * than 150.000 points. This method is slightly slower, but safe.
  *
- * @function #arrayMax
- * @memberof Highcharts
- * @param {Array} data - An array of numbers.
- * @returns {Number} The highest number.
+ * @function Highcharts.arrayMax
+ *
+ * @param {Array} data
+ *        An array of numbers.
+ *
+ * @return {number}
+ *         The highest number.
  */
 H.arrayMax = function (data) {
     var i = data.length,
@@ -1195,12 +1656,13 @@ H.arrayMax = function (data) {
  * the given object. It loops all properties and invokes destroy if there is a
  * destroy method. The property is then delete.
  *
- * @function #destroyObjectProperties
- * @memberof Highcharts
- * @param {Object} obj - The object to destroy properties on.
- * @param {Object} [except] - Exception, do not destroy this property, only
- *    delete it.
+ * @function Highcharts.destroyObjectProperties
+ *
+ * @param {*} obj
+ *        The object to destroy properties on.
  *
+ * @param {*} [except]
+ *        Exception, do not destroy this property, only delete it.
  */
 H.destroyObjectProperties = function (obj, except) {
     H.objectEach(obj, function (val, n) {
@@ -1219,10 +1681,10 @@ H.destroyObjectProperties = function (obj, except) {
 /**
  * Discard a HTML element by moving it to the bin and delete.
  *
- * @function #discardElement
- * @memberof Highcharts
- * @param {HTMLDOMElement} element - The HTML node to discard.
+ * @function Highcharts.discardElement
  *
+ * @param {Highcharts.HTMLDOMElement} element
+ *        The HTML node to discard.
  */
 H.discardElement = function (element) {
     var garbageBin = H.garbageBin;
@@ -1241,11 +1703,16 @@ H.discardElement = function (element) {
 /**
  * Fix JS round off float errors.
  *
- * @function #correctFloat
- * @memberof Highcharts
- * @param {Number} num - A float number to fix.
- * @param {Number} [prec=14] - The precision.
- * @returns {Number} The corrected float number.
+ * @function Highcharts.correctFloat
+ *
+ * @param {number} num
+ *        A float number to fix.
+ *
+ * @param {number} [prec=14]
+ *        The precision.
+ *
+ * @return {number}
+ *         The corrected float number.
  */
 H.correctFloat = function (num, prec) {
     return parseFloat(
@@ -1257,13 +1724,17 @@ H.correctFloat = function (num, prec) {
  * Set the global animation to either a given value, or fall back to the given
  * chart's animation option.
  *
- * @function #setAnimation
- * @memberof Highcharts
- * @param {Boolean|Animation} animation - The animation object.
- * @param {Object} chart - The chart instance.
+ * @function Highcharts.setAnimation
+ *
+ * @param {boolean|Highcharts.AnimationOptionsObject} animation
+ *        The animation object.
+ *
+ * @param {Highcharts.Chart} chart
+ *        The chart instance.
  *
- * @todo This function always relates to a chart, and sets a property on the
- *        renderer, so it should be moved to the SVGRenderer.
+ * @todo
+ * This function always relates to a chart, and sets a property on the renderer,
+ * so it should be moved to the SVGRenderer.
  */
 H.setAnimation = function (animation, chart) {
     chart.renderer.globalAnimation = H.pick(
@@ -1277,12 +1748,14 @@ H.setAnimation = function (animation, chart) {
  * Get the animation in object form, where a disabled animation is always
  * returned as `{ duration: 0 }`.
  *
- * @function #animObject
- * @memberof Highcharts
- * @param {Boolean|AnimationOptions} animation - An animation setting. Can be an
- *        object with duration, complete and easing properties, or a boolean to
- *        enable or disable.
- * @returns {AnimationOptions} An object with at least a duration property.
+ * @function Highcharts.animObject
+ *
+ * @param {boolean|Highcharts.AnimationOptionsObject} animation
+ *        An animation setting. Can be an object with duration, complete and
+ *        easing properties, or a boolean to enable or disable.
+ *
+ * @return {Highcharts.AnimationOptionsObject}
+ *         An object with at least a duration property.
  */
 H.animObject = function (animation) {
     return H.isObject(animation) ?
@@ -1292,6 +1765,8 @@ H.animObject = function (animation) {
 
 /**
  * The time unit lookup
+ *
+ * @ignore
  */
 H.timeUnits = {
     millisecond: 1,
@@ -1307,18 +1782,28 @@ H.timeUnits = {
 /**
  * Format a number and return a string based on input settings.
  *
- * @function #numberFormat
- * @memberof Highcharts
- * @param {Number} number - The input number to format.
- * @param {Number} decimals - The amount of decimals. A value of -1 preserves
- *        the amount in the input number.
- * @param {String} [decimalPoint] - The decimal point, defaults to the one given
- *        in the lang options, or a dot.
- * @param {String} [thousandsSep] - The thousands separator, defaults to the one
- *        given in the lang options, or a space character.
- * @returns {String} The formatted number.
+ * @sample highcharts/members/highcharts-numberformat/
+ *         Custom number format
+ *
+ * @function Highcharts.numberFormat
+ *
+ * @param {number} number
+ *        The input number to format.
+ *
+ * @param {number} decimals
+ *        The amount of decimals. A value of -1 preserves the amount in the
+ *        input number.
  *
- * @sample highcharts/members/highcharts-numberformat/ Custom number format
+ * @param {string} [decimalPoint]
+ *        The decimal point, defaults to the one given in the lang options, or
+ *        a dot.
+ *
+ * @param {string} [thousandsSep]
+ *        The thousands separator, defaults to the one given in the lang
+ *        options, or a space character.
+ *
+ * @return {string}
+ *         The formatted number.
  */
 H.numberFormat = function (number, decimals, decimalPoint, thousandsSep) {
     number = +number || 0;
@@ -1406,8 +1891,14 @@ H.numberFormat = function (number, decimals, decimalPoint, thousandsSep) {
 
 /**
  * Easing definition
- * @ignore
- * @param   {Number} pos Current position, ranging from 0 to 1.
+ *
+ * @private
+ * @function Math.easeInOutSine
+ *
+ * @param {number} pos
+ *        Current position, ranging from 0 to 1.
+ *
+ * @return {number}
  */
 Math.easeInOutSine = function (pos) {
     return -0.5 * (Math.cos(Math.PI * pos) - 1);
@@ -1418,12 +1909,19 @@ Math.easeInOutSine = function (pos) {
  * properties. For width and height, the dimension of the inner box (excluding
  * padding) is returned. Used for fitting the chart within the container.
  *
- * @function #getStyle
- * @memberof Highcharts
- * @param {HTMLDOMElement} el - A HTML element.
- * @param {String} prop - The property name.
- * @param {Boolean} [toInt=true] - Parse to integer.
- * @returns {Number} - The numeric value.
+ * @function Highcharts.getStyle
+ *
+ * @param {Highcharts.HTMLDOMElement} el
+ *        An HTML element.
+ *
+ * @param {string} prop
+ *        The property name.
+ *
+ * @param {boolean} [toInt=true]
+ *        Parse to integer.
+ *
+ * @return {number}
+ *         The numeric value.
  */
 H.getStyle = function (el, prop, toInt) {
 
@@ -1465,12 +1963,19 @@ H.getStyle = function (el, prop, toInt) {
 /**
  * Search for an item in an array.
  *
- * @function #inArray
- * @memberof Highcharts
- * @param {*} item - The item to search for.
- * @param {arr} arr - The array or node collection to search in.
- * @param {fromIndex} [fromIndex=0] - The index to start searching from.
- * @returns {Number} - The index within the array, or -1 if not found.
+ * @function Highcharts.inArray
+ *
+ * @param {*} item
+ *        The item to search for.
+ *
+ * @param {Array} arr
+ *        The array or node collection to search in.
+ *
+ * @param {number} [fromIndex=0]
+ *        The index to start searching from.
+ *
+ * @return {number}
+ *         The index within the array, or -1 if not found.
  */
 H.inArray = function (item, arr, fromIndex) {
     return (
@@ -1482,13 +1987,17 @@ H.inArray = function (item, arr, fromIndex) {
 /**
  * Filter an array by a callback.
  *
- * @function #grep
- * @memberof Highcharts
- * @param {Array} arr - The array to filter.
- * @param {Function} callback - The callback function. The function receives the
- *        item as the first argument. Return `true` if the item is to be
- *        preserved.
- * @returns {Array} - A new, filtered array.
+ * @function Highcharts.grep
+ *
+ * @param {Array} arr
+ *        The array to filter.
+ *
+ * @param {Function} callback
+ *        The callback function. The function receives the item as the first
+ *        argument. Return `true` if the item is to be preserved.
+ *
+ * @return {Array}
+ *         A new, filtered array.
  */
 H.grep = function (arr, callback) {
     return (H.filterPolyfill || Array.prototype.filter).call(arr, callback);
@@ -1498,13 +2007,17 @@ H.grep = function (arr, callback) {
  * Return the value of the first element in the array that satisfies the
  * provided testing function.
  *
- * @function #find
- * @memberof Highcharts
- * @param {Array} arr - The array to test.
- * @param {Function} callback - The callback function. The function receives the
- *        item as the first argument. Return `true` if this item satisfies the
- *        condition.
- * @returns {Mixed} - The value of the element.
+ * @function Highcharts.find
+ *
+ * @param {Array} arr
+ *        The array to test.
+ *
+ * @param {Function} callback
+ *        The callback function. The function receives the item as the first
+ *        argument. Return `true` if this item satisfies the condition.
+ *
+ * @return {*}
+ *         The value of the element.
  */
 H.find = Array.prototype.find ?
     function (arr, callback) {
@@ -1526,13 +2039,19 @@ H.find = Array.prototype.find ?
  * Test whether at least one element in the array passes the test implemented by
  * the provided function.
  *
- * @function #some
- * @memberof Highcharts
- * @param  {Array}   arr  The array to test
- * @param  {Function} fn  The function to run on each item. Return truty to pass
- *                        the test. Receives arguments `currentValue`, `index`
- *                        and `array`.
- * @param  {Object}   ctx The context.
+ * @function Highcharts.some
+ *
+ * @param {Array} arr
+ *        The array to test
+ *
+ * @param {Function} fn
+ *        The function to run on each item. Return truty to pass the test.
+ *        Receives arguments `currentValue`, `index` and `array`.
+ *
+ * @param {*} ctx
+ *        The context.
+ *
+ * @return {boolean}
  */
 H.some = function (arr, fn, ctx) {
     return (H.somePolyfill || Array.prototype.some).call(arr, fn, ctx);
@@ -1541,12 +2060,16 @@ H.some = function (arr, fn, ctx) {
 /**
  * Map an array by a callback.
  *
- * @function #map
- * @memberof Highcharts
- * @param {Array} arr - The array to map.
- * @param {Function} fn - The callback function. Return the new value for the
- *        new array.
- * @returns {Array} - A new array item with modified items.
+ * @function Highcharts.map
+ *
+ * @param {Array} arr
+ *        The array to map.
+ *
+ * @param {Function} fn
+ *        The callback function. Return the new value for the new array.
+ *
+ * @return {Array}
+ *         A new array item with modified items.
  */
 H.map = function (arr, fn) {
     var results = [],
@@ -1563,10 +2086,13 @@ H.map = function (arr, fn) {
 /**
  * Returns an array of a given object's own properties.
  *
- * @function #keys
- * @memberof Highcharts
- * @param {Object} obj - The object of which the properties are to be returned.
- * @returns {Array} - An array of strings that represents all the properties.
+ * @function Highcharts.keys
+ *
+ * @param {*} obj
+ *        The object of which the properties are to be returned.
+ *
+ * @return {Array<string>}
+ *         An array of strings that represents all the properties.
  */
 H.keys = function (obj) {
     return (H.keysPolyfill || Object.keys).call(undefined, obj);
@@ -1575,14 +2101,21 @@ H.keys = function (obj) {
 /**
  * Reduce an array to a single value.
  *
- * @function #reduce
- * @memberof Highcharts
- * @param {Array} arr - The array to reduce.
- * @param {Function} fn - The callback function. Return the reduced value.
- *  Receives 4 arguments: Accumulated/reduced value, current value, current
- *  array index, and the array.
- * @param {Mixed} initialValue - The initial value of the accumulator.
- * @returns {Mixed} - The reduced value.
+ * @function Highcharts.reduce
+ *
+ * @param {Array<*>} arr
+ *        The array to reduce.
+ *
+ * @param {Function} fn
+ *        The callback function. Return the reduced value. Receives 4
+ *        arguments: Accumulated/reduced value, current value, current array
+ *        index, and the array.
+ *
+ * @param {*} initialValue
+ *        The initial value of the accumulator.
+ *
+ * @return {*}
+ *         The reduced value.
  */
 H.reduce = function (arr, func, initialValue) {
     var fn = (H.reducePolyfill || Array.prototype.reduce);
@@ -1595,11 +2128,14 @@ H.reduce = function (arr, func, initialValue) {
 /**
  * Get the element's offset position, corrected for `overflow: auto`.
  *
- * @function #offset
- * @memberof Highcharts
- * @param {HTMLDOMElement} el - The HTML element.
- * @returns {Object} An object containing `left` and `top` properties for the
- * position in the page.
+ * @function Highcharts.offset
+ *
+ * @param {Highcharts.HTMLDOMElement} el
+ *        The HTML element.
+ *
+ * @return {Highcharts.OffsetObject}
+ *         An object containing `left` and `top` properties for the position in
+ *         the page.
  */
 H.offset = function (el) {
     var docElem = doc.documentElement,
@@ -1618,18 +2154,21 @@ H.offset = function (el) {
 /**
  * Stop running animation.
  *
- * @todo A possible extension to this would be to stop a single property, when
+ * @function Highcharts.stop
+ *
+ * @param {Highcharts.SVGElement} el
+ *        The SVGElement to stop animation on.
+ *
+ * @param {string} [prop]
+ *        The property to stop animating. If given, the stop method will stop a
+ *        single property from animating, while others continue.
+ *
+ * @todo
+ * A possible extension to this would be to stop a single property, when
  * we want to continue animating others. Then assign the prop to the timer
  * in the Fx.run method, and check for the prop here. This would be an
  * improvement in all cases where we stop the animation from .attr. Instead of
  * stopping everything, we can just stop the actual attributes we're setting.
- *
- * @function #stop
- * @memberof Highcharts
- * @param {SVGElement} el - The SVGElement to stop animation on.
- * @param {string} [prop] - The property to stop animating. If given, the stop
- *    method will stop a single property from animating, while others continue.
- *
  */
 H.stop = function (el, prop) {
 
@@ -1646,14 +2185,19 @@ H.stop = function (el, prop) {
 /**
  * Iterate over an array.
  *
- * @function #each
- * @memberof Highcharts
- * @param {Array} arr - The array to iterate over.
- * @param {Function} fn - The iterator callback. It passes three arguments:
- * * item - The array item.
- * * index - The item's index in the array.
- * * arr - The array that each is being applied to.
- * @param {Object} [ctx] The context.
+ * @function Highcharts.each<T>
+ *
+ * @param {Array<T>} arr
+ *        The array to iterate over.
+ *
+ * @param {Highcharts.EachCallbackFunction<T>} fn
+ *        The iterator callback. It passes three arguments:
+ *        * item - The array item.
+ *        * index - The item's index in the array.
+ *        * arr - The array that each is being applied to.
+ *
+ * @param {*} [ctx]
+ *        The context.
  */
 H.each = function (arr, fn, ctx) { // modern browsers
     return (H.forEachPolyfill || Array.prototype.forEach).call(arr, fn, ctx);
@@ -1662,14 +2206,19 @@ H.each = function (arr, fn, ctx) { // modern browsers
 /**
  * Iterate over object key pairs in an object.
  *
- * @function #objectEach
- * @memberof Highcharts
- * @param  {Object}   obj - The object to iterate over.
- * @param  {Function} fn  - The iterator callback. It passes three arguments:
- * * value - The property value.
- * * key - The property key.
- * * obj - The object that objectEach is being applied to.
- * @param  {Object}   ctx The context
+ * @function Highcharts.objectEach
+ *
+ * @param {*} obj
+ *        The object to iterate over.
+ *
+ * @param {Highcharts.ObjectEachCallbackFunction} fn
+ *        The iterator callback. It passes three arguments:
+ *        * value - The property value.
+ *        * key - The property key.
+ *        * obj - The object that objectEach is being applied to.
+ *
+ * @param {*} [ctx]
+ *        The context.
  */
 H.objectEach = function (obj, fn, ctx) {
     for (var key in obj) {
@@ -1682,20 +2231,28 @@ H.objectEach = function (obj, fn, ctx) {
 /**
  * Add an event listener.
  *
- * @function #addEvent
- * @memberof Highcharts
- * @param {Object} el - The element or object to add a listener to. It can be a
+ * @function Highcharts.addEvent
+ *
+ * @param {*} el
+ *        The element or object to add a listener to. It can be a
  *        {@link HTMLDOMElement}, an {@link SVGElement} or any other object.
- * @param {String} type - The event type.
- * @param {Function} fn - The function callback to execute when the event is
- *        fired.
- * @param {Object} options
+ *
+ * @param {string} type
+ *        The event type.
+ *
+ * @param {Highcharts.EventCallbackFunction} fn
+ *        The function callback to execute when the event is fired.
+ *
+ * @param {Highcharts.Dictionary<*>} options
  *        Event options
- * @param {Number} options.order
+ *
+ * @param {number} options.order
  *        The order the event handler should be called. This opens for having
  *        one handler be called before another, independent of in which order
  *        they were added.
- * @returns {Function} A callback function to remove the added event.
+ *
+ * @return {Function}
+ *         A callback function to remove the added event.
  */
 H.addEvent = function (el, type, fn, options) {
 
@@ -1745,14 +2302,18 @@ H.addEvent = function (el, type, fn, options) {
 /**
  * Remove an event that was added with {@link Highcharts#addEvent}.
  *
- * @function #removeEvent
- * @memberof Highcharts
- * @param {Object} el - The element to remove events on.
- * @param {String} [type] - The type of events to remove. If undefined, all
- *        events are removed from the element.
- * @param {Function} [fn] - The specific callback to remove. If undefined, all
- *        events that match the element and optionally the type are removed.
+ * @function Highcharts.removeEvent
+ *
+ * @param {*} el
+ *        The element to remove events on.
  *
+ * @param {string} [type]
+ *        The type of events to remove. If undefined, all events are removed
+ *        from the element.
+ *
+ * @param {Function} [fn]
+ *        The specific callback to remove. If undefined, all events that match
+ *        the element and optionally the type are removed.
  */
 H.removeEvent = function (el, type, fn) {
 
@@ -1821,16 +2382,22 @@ H.removeEvent = function (el, type, fn) {
 /**
  * Fire an event that was registered with {@link Highcharts#addEvent}.
  *
- * @function #fireEvent
- * @memberof Highcharts
- * @param {Object} el - The object to fire the event on. It can be a
- *        {@link HTMLDOMElement}, an {@link SVGElement} or any other object.
- * @param {String} type - The type of event.
- * @param {Object} [eventArguments] - Custom event arguments that are passed on
- *        as an argument to the event handler.
- * @param {Function} [defaultFunction] - The default function to execute if the
- *        other listeners haven't returned false.
+ * @function Highcharts.fireEvent
+ *
+ * @param {*} el
+ *        The object to fire the event on. It can be a {@link HTMLDOMElement},
+ *        an {@link SVGElement} or any other object.
+ *
+ * @param {string} type
+ *        The type of event.
  *
+ * @param {Highcharts.Dictionary<*>} [eventArguments]
+ *        Custom event arguments that are passed on as an argument to the event
+ *        handler.
+ *
+ * @param {Function} [defaultFunction]
+ *        The default function to execute if the other listeners haven't
+ *        returned false.
  */
 H.fireEvent = function (el, type, eventArguments, defaultFunction) {
     var e,
@@ -1900,32 +2467,21 @@ H.fireEvent = function (el, type, eventArguments, defaultFunction) {
     }
 };
 
-/**
- * An animation configuration. Animation configurations can also be defined as
- * booleans, where `false` turns off animation and `true` defaults to a duration
- * of 500ms.
- * @typedef {Object} AnimationOptions
- * @property {Number} duration - The animation duration in milliseconds.
- * @property {String} [easing] - The name of an easing function as defined on
- *     the `Math` object.
- * @property {Function} [complete] - A callback function to exectute when the
- *     animation finishes.
- * @property {Function} [step] - A callback function to execute on each step of
- *     each attribute or CSS property that's being animated. The first argument
- *     contains information about the animation and progress.
- */
-
-
 /**
  * The global animate method, which uses Fx to create individual animators.
  *
- * @function #animate
- * @memberof Highcharts
- * @param {HTMLDOMElement|SVGElement} el - The element to animate.
- * @param {Object} params - An object containing key-value pairs of the
- *        properties to animate. Supports numeric as pixel-based CSS properties
- *        for HTML objects and attributes for SVGElements.
- * @param {AnimationOptions} [opt] - Animation options.
+ * @function Highcharts.animate
+ *
+ * @param {Highcharts.HTMLDOMElement|Highcharts.SVGElement} el
+ *        The element to animate.
+ *
+ * @param {Highcharts.HTMLAttributes|Highcharts.SVGAttributes} params
+ *        An object containing key-value pairs of the properties to animate.
+ *        Supports numeric as pixel-based CSS properties for HTML objects and
+ *        attributes for SVGElements.
+ *
+ * @param {Highcharts.AnimationOptionsObject} [opt]
+ *        Animation options.
  */
 H.animate = function (el, params, opt) {
     var start,
@@ -1988,20 +2544,30 @@ H.animate = function (el, params, opt) {
 /**
  * Factory to create new series prototypes.
  *
- * @function #seriesType
- * @memberof Highcharts
- *
- * @param {String} type - The series type name.
- * @param {String} parent - The parent series type name. Use `line` to inherit
- *        from the basic {@link Series} object.
- * @param {Object} options - The additional default options that is merged with
- *        the parent's options.
- * @param {Object} props - The properties (functions and primitives) to set on
- *        the new prototype.
- * @param {Object} [pointProps] - Members for a series-specific extension of the
- *        {@link Point} prototype if needed.
- * @returns {*} - The newly created prototype as extended from {@link Series}
- * or its derivatives.
+ * @function Highcharts.seriesType
+ *
+ * @param {string} type
+ *        The series type name.
+ *
+ * @param {string} parent
+ *        The parent series type name. Use `line` to inherit from the basic
+ *        {@link Series} object.
+ *
+ * @param {*} options
+ *        The additional default options that is merged with the parent's
+ *        options.
+ *
+ * @param {*} props
+ *        The properties (functions and primitives) to set on the new
+ *        prototype.
+ *
+ * @param {*} [pointProps]
+ *        Members for a series-specific extension of the {@link Point}
+ *        prototype if needed.
+ *
+ * @return {Highcharts.Series}
+ *         The newly created prototype as extended from {@link Series} or its
+ *         derivatives.
  */
 // docs: add to API + extending Highcharts
 H.seriesType = function (type, parent, options, props, pointProps) {
@@ -2029,14 +2595,17 @@ H.seriesType = function (type, parent, options, props, pointProps) {
 };
 
 /**
- * Get a unique key for using in internal element id's and pointers. The key
- * is composed of a random hash specific to this Highcharts instance, and a
+ * Get a unique key for using in internal element id's and pointers. The key is
+ * composed of a random hash specific to this Highcharts instance, and a
  * counter.
- * @function #uniqueKey
- * @memberof Highcharts
- * @return {string} The key.
+ *
  * @example
  * var id = H.uniqueKey(); // => 'highcharts-x45f6hp-0'
+ *
+ * @function Highcharts.uniqueKey
+ *
+ * @return {string}
+ *         A unique key.
  */
 H.uniqueKey = (function () {
 
@@ -2048,10 +2617,36 @@ H.uniqueKey = (function () {
     };
 }());
 
-/**
- * Register Highcharts as a plugin in jQuery
- */
+// Register Highcharts as a plugin in jQuery
 if (win.jQuery) {
+
+    /**
+     * Highcharts-extended JQuery.
+     *
+     * @external JQuery
+     */
+
+    /**
+     * Factory function to create a chart in the current JQuery selector
+     * element.
+     *
+     * @function external:JQuery#highcharts
+     *
+     * @param {"Chart"|"Map"|"StockChart"|string} [className]
+     *        Name of the factory class in the Highcharts namespace.
+     *
+     * @param {Highcharts.Options} options
+     *        The chart options structure.
+     *
+     * @param {Highcharts.ChartCallbackFunction} [callback]
+     *        Function to run when the chart has loaded and and all external
+     *        images are loaded. Defining a [chart.event.load
+     *        ](https://api.highcharts.com/highcharts/chart.events.load) handler
+     *        is equivalent.
+     *
+     * @return {JQuery}
+     *         The current JQuery selector.
+     */
     win.jQuery.fn.highcharts = function () {
         var args = [].slice.call(arguments);