Improve JSDoc output

.jsdoc

@@ -3,5 +3,10 @@
   "opts": {
     "destination": "dist/doc",
     "readme": "index.md"
+  },
+  "templates": {
+    "default": {
+      "useLongnameInNav": true
+    }
   }
 }

index.md

@@ -1,4 +1,4 @@
-# Shifty
+# **Shifty**
 
 Shifty is a JavaScript tweening engine designed to fit all of your animation needs. Core features include:
 
@@ -9,7 +9,7 @@ Shifty is a JavaScript tweening engine designed to fit all of your animation nee
 
 Shifty is a low-level animation solution.  This means that it does not perform any rendering, but it can be integrated into whatever rendering mechanism is most appropriate for your project.  Shifty is meant to be a simpler, more lightweight and flexible alternative to richer tools like the excellent [GreenSock animation platform](https://greensock.com/).  While GreenSock edges it out in raw performance comparisons, [Shifty's performance is quite good](http://codepen.io/GreenSock/pen/10a1790cf256ac78ad65d5cc52c39126/) and offers a simpler, smaller package.  This can be critical for some projects, particularly on mobile devices.  [Just ask Yelp](http://engineeringblog.yelp.com/2015/01/animating-the-mobile-web.html).
 
-Shifty is the heart of [Rekapi](http://rekapi.com/), a higher-level library for making keyframe animations. Shifty is also a low-level part of [Stylie](http://jeremyckahn.github.io/stylie/), a graphical animation tool.
+Shifty is the heart of [Rekapi](http://rekapi.com/), a higher-level library for making keyframe animations. Shifty is also a low-level part of [Stylie](http://jeremyckahn.github.io/stylie/) and [Mantra](http://jeremyckahn.github.io/mantra/), a suite of graphical animation tools.
 
 To create a basic tween, you could have something like this:
 

src/main.js

@@ -1,12 +1,14 @@
 import {
   Tweenable,
-  tween,
-  now
+  tween
 } from './shifty.core';
 
 import { interpolate } from './shifty.interpolate';
 import { setBezierFunction, unsetBezierFunction } from './shifty.bezier';
 
+/**
+ * @namespace shifty
+ */
 export {
   Tweenable,
   tween,

src/shifty.bezier.js

@@ -145,7 +145,7 @@ const getCubicBezierTransition = (x1, y1, x2, y2) =>
  * total control over the easing curve.  Matthew Lein's
  * [Ceaser](http://matthewlein.com/ceaser/) is a useful tool for visualizing
  * the curves you can make with this function.
- * @method setBezierFunction
+ * @method shifty.setBezierFunction
  * @param {string} name The name of the easing curve.  Overwrites the old
  * easing function on [`Tweenable.formulas`]{@link Tweenable.formulas} if it
  * exists.
@@ -171,8 +171,8 @@ export const setBezierFunction = (name, x1, y1, x2, y2) =>
  * Tweenable.formulas}.  Be careful with this method, as it `delete`s whatever
  * easing formula matches `name` (which means you can delete standard Shifty
  * easing functions).
- * @method unsetBezierFunction
+ * @method shifty.unsetBezierFunction
  * @param {string} name The name of the easing function to delete.
- * @return {function}
+ * @return {Boolean} Whether or not the functions was `delete`d.
  */
 export const unsetBezierFunction = name => delete Tweenable.formulas[name];

src/shifty.core.js

@@ -136,10 +136,11 @@ export const composeEasingObject = (fromTweenParams, easing = DEFAULT_EASING) =>
 
 export class Tweenable {
   /**
+   * @constructs shifty.Tweenable
    * @param {Object=} initialState The values that the initial tween should
    * start at if a `from` object is not provided to `tween` or `setConfig`.
    * @param {Object=} config Configuration object to be passed to
-   * [`setConfig`]{@link Tweenable#setConfig}.
+   * [`setConfig`]{@link shifty.Tweenable#setConfig}.
    */
   constructor (initialState = {}, config = undefined) {
     this._currentState = initialState;
@@ -177,7 +178,7 @@ export class Tweenable {
   /**
    * Handles the update logic for one step of a tween.
    * @param {number=} currentTimeOverride Needed for accurate timestamp in
-   * Tweenable#seek.
+   * shifty.Tweenable#seek.
    * @private
    */
   _timeoutHandler (currentTimeOverride) {
@@ -239,10 +240,10 @@ export class Tweenable {
 
   /**
    * Configure and start a tween.
-   * @method Tweenable#tween
-   * @param {Object=} config Configuration object to be passed to
-   * [`setConfig`]{@link Tweenable#setConfig}.
-   * @return Promise
+   * @method shifty.Tweenable#tween
+   * @param {Object=} config See `config` options for `{@link
+   * shifty.Tweenable#setConfig}`
+   * @return {Promise}
    */
   tween (config = undefined) {
     if (this._isTweening) {
@@ -263,10 +264,10 @@ export class Tweenable {
   /**
    * Configure a tween that will start at some point in the future.
    *
-   * @method Tweenable#setConfig
+   * @method shifty.Tweenable#setConfig
    * @param {Object} config See below
-   * @property {Object=} config.from Starting position.  If omitted, `get` is
-   * used.
+   * @property {Object=} config.from Starting position.  If omitted, `{@link
+   * shifty.Tweenable#get}` is used.
    * @property {Object=} config.to Ending position.
    * @property {number=} config.duration How many milliseconds to animate for.
    * @property {number=} config.delay  How many milliseconds to wait before
@@ -283,7 +284,7 @@ export class Tweenable {
    * curve name(s) or function(s) to use for the tween.
    * @property {*=} config.attachment Cached value that is passed to the
    * `step`/`start` functions.
-   * @return Tweenable
+   * @return {Tweenable}
    */
   setConfig (config = {}) {
     this._configured = true;
@@ -333,15 +334,15 @@ export class Tweenable {
   }
 
   /**
-   * @method Tweenable#get
+   * @method shifty.Tweenable#get
    * @return {Object} The current state.
    */
   get () {
     return clone(this._currentState);
   }
 
   /**
-   * @method Tweenable#set
+   * @method shifty.Tweenable#set
    * @param {Object} state The state to set.
    * @description Set the current state.
    */
@@ -353,8 +354,8 @@ export class Tweenable {
    * Pause a tween.  Paused tweens can be resumed from the point at which they
    * were paused.  This is different from `stop`, as that method causes a tween
    * to start over when it is resumed.
-   * @method Tweenable#pause
-   * @return Tweenable
+   * @method shifty.Tweenable#pause
+   * @return {Tweenable}
    */
   pause () {
     this._pausedAtTime = Tweenable.now();
@@ -365,8 +366,8 @@ export class Tweenable {
 
   /**
    * Resume a paused tween.
-   * @method Tweenable#resume
-   * @return Promise
+   * @method shifty.Tweenable#resume
+   * @return {Promise}
    */
   resume () {
     if (this._isPaused) {
@@ -384,10 +385,10 @@ export class Tweenable {
    * Move the state of the animation to a specific point in the tween's
    * timeline.  If the animation is not running, this will cause the `step`
    * handlers to be called.
-   * @method Tweenable#seek
+   * @method shifty.Tweenable#seek
    * @param {millisecond} millisecond The millisecond of the animation to seek
    * to.  This must not be less than `0`.
-   * @return Tweenable
+   * @return {Tweenable}
    */
   seek (millisecond) {
     millisecond = Math.max(millisecond, 0);
@@ -419,8 +420,8 @@ export class Tweenable {
    * its current state, and the tween promise is not resolved.  If `true`, the
    * tweened object's values are instantly set to the target values, and the
    * promise is resolved.
-   * @method Tweenable#stop
-   * @return Tweenable
+   * @method shifty.Tweenable#stop
+   * @return {Tweenable}
    */
   stop (gotoEnd) {
     this._isTweening = false;
@@ -457,8 +458,9 @@ export class Tweenable {
   }
 
   /**
-   * @method Tweenable#isPlaying
-   * @return {boolean} Whether or not a tween is running.
+   * Whether or not a tween is running.
+   * @method shifty.Tweenable#isPlaying
+   * @return {boolean}
    */
   isPlaying () {
     return this._isTweening && !this._isPaused;
@@ -472,7 +474,7 @@ export class Tweenable {
    * is used if available, otherwise
    * [`setTimeout`](https://developer.mozilla.org/en-US/docs/Web/API/Window.setTimeout)
    * is used.
-   * @method Tweenable#setScheduleFunction
+   * @method shifty.Tweenable#setScheduleFunction
    * @param {Function(Function,number)} scheduleFunction The function to be
    * used to schedule the next frame to be rendered.
    */
@@ -483,7 +485,7 @@ export class Tweenable {
   /**
    * `delete` all "own" properties.  Call this when the `Tweenable` instance
    * is no longer needed to free memory.
-   * @method Tweenable#dispose
+   * @method shifty.Tweenable#dispose
    */
   dispose () {
     each(this, prop => delete this[prop]);
@@ -492,8 +494,8 @@ export class Tweenable {
 
 Object.assign(Tweenable, {
   /**
-   * @memberof Tweenable
-   * @type Object.<Function(number)>
+   * @memberof shifty.Tweenable
+   * @type {Object.<Function(number)>}
    * @static
    * @description A static Object of easing functions that can by used by
    * Shifty.
@@ -504,10 +506,12 @@ Object.assign(Tweenable, {
 });
 
 /**
- * @param {Object=} config
+ * @method shifty.tween
+ * @param {Object=} config See `config` options for `{@link
+ * shifty.Tweenable#setConfig}`
  * @description Standalone convenience method that functions identically to
- * [`Tweenable#tween`]{@link Tweenable#tween}.  You can use this to create
- * tweens without needing to set up a [`Tweenable`]{@link Tweenable} instance.
+ * [`shifty.Tweenable#tween`]{@link shifty.Tweenable#tween}.  You can use this to create
+ * tweens without needing to set up a `{@link shifty.Tweenable}` instance.
  *
  *     import { tween } from 'shifty';
  *

src/shifty.interpolate.js

@@ -28,8 +28,7 @@ mockTweenable._filterArgs = [];
  *     console.log(interpolatedValues);
  *     // {opacity: 0.5, width: "150px", color: "rgb(127,127,127)"}
  *
- * @static
- * @method interpolate
+ * @method shifty.interpolate
  * @param {Object} from The starting values to tween from.
  * @param {Object} targetState The ending values to tween to.
  * @param {number} position The normalized position value (between `0.0` and

src/shifty.token.js

@@ -1,25 +1,24 @@
 /**
- * This module adds string interpolation support to Shifty.
+ * This module adds string interpolation support to Shifty.  It "just works;"
+ * it does not expose a public API.
  *
  * The Token extension allows Shifty to tween numbers inside of strings.  Among
  * other things, this allows you to animate CSS properties.  For example, you
  * can do this:
  *
- *     var tweenable = new Tweenable();
- *     tweenable.tween({
+ *     import { tween } from 'shifty';
+ *
+ *     tween({
  *       from: { transform: 'translateX(45px)' },
  *       to: { transform: 'translateX(90xp)' }
  *     });
  *
  * `translateX(45)` will be tweened to `translateX(90)`.  To demonstrate:
  *
- *     var tweenable = new Tweenable();
- *     tweenable.tween({
+ *     tween({
  *       from: { transform: 'translateX(45px)' },
  *       to: { transform: 'translateX(90px)' },
- *       step: function (state) {
- *         console.log(state.transform);
- *       }
+ *       step: state => console.log(state.transform)
  *     });
  *
  * The above snippet will log something like this in the console:
@@ -32,13 +31,10 @@
  *
  * Another use for this is animating colors:
  *
- *     var tweenable = new Tweenable();
- *     tweenable.tween({
+ *     tween({
  *       from: { color: 'rgb(0,255,0)' },
  *       to: { color: 'rgb(255,0,255)' },
- *       step: function (state) {
- *         console.log(state.color);
- *       }
+ *       step: state => console.log(state.color)
  *     });
  *
  * The above snippet will log something like this:
@@ -54,13 +50,10 @@
  * converted into the equivalent RGB output values.  This is done to optimize
  * for performance.
  *
- *     var tweenable = new Tweenable();
- *     tweenable.tween({
+ *     tween({
  *       from: { color: '#0f0' },
  *       to: { color: '#f0f' },
- *       step: function (state) {
- *         console.log(state.color);
- *       }
+ *       step: state => console.log(state.color)
  *     });
  *
  * This snippet will generate the same output as the one before it because
@@ -78,14 +71,11 @@
  * some CSS properties have multiple values in them, and you might need to
  * tween each value along its own easing curve.  A basic example:
  *
- *     var tweenable = new Tweenable();
- *     tweenable.tween({
+ *     tween({
  *       from: { transform: 'translateX(0px) translateY(0px)' },
  *       to: { transform:   'translateX(100px) translateY(100px)' },
  *       easing: { transform: 'easeInQuad' },
- *       step: function (state) {
- *         console.log(state.transform);
- *       }
+ *       step: state => console.log(state.transform)
  *     });
  *
  * The above snippet will create values like this:
@@ -101,14 +91,11 @@
  * points and both use the same easing curve.  We can also tween `translateX`
  * and `translateY` along independent curves:
  *
- *     var tweenable = new Tweenable();
- *     tweenable.tween({
+ *     tween({
  *       from: { transform: 'translateX(0px) translateY(0px)' },
  *       to: { transform:   'translateX(100px) translateY(100px)' },
  *       easing: { transform: 'easeInQuad bounce' },
- *       step: function (state) {
- *         console.log(state.transform);
- *       }
+ *       step: state => console.log(state.transform)
  *     });
  *
  * The above snippet will create values like this:
@@ -127,7 +114,7 @@
  * The order of the space-separated easing curves correspond the token values
  * they apply to.  If there are more token values than easing curves listed,
  * the last easing curve listed is used.
- * @submodule Tweenable.token
+ * @module token
  */
 
 // token function is defined above only so that dox-foundation sees it as