comments for transition refactor

src/transition/queue.js

@@ -2,6 +2,12 @@ var _ = require('../util')
 var queue = []
 var queued = false
 
+/**
+ * Push a job into the queue.
+ *
+ * @param {Function} job
+ */
+
 exports.push = function (job) {
   queue.push(job)
   if (!queued) {

src/transition/transition.js

@@ -11,6 +11,16 @@ var doc = typeof document === 'undefined' ? null : document
 var TYPE_TRANSITION = 1
 var TYPE_ANIMATION = 2
 
+/**
+ * A Transition object that encapsulates the state and logic
+ * of the transition.
+ *
+ * @param {Element} el
+ * @param {String} id
+ * @param {Object} hooks
+ * @param {Vue} vm
+ */
+
 function Transition (el, id, hooks, vm) {
   this.el = el
   this.enterClass = id + '-enter'
@@ -35,6 +45,13 @@ function Transition (el, id, hooks, vm) {
 
 var p = Transition.prototype
 
+/**
+ * Start an entering transition.
+ *
+ * @param {Function} op - insert/show the element
+ * @param {Function} [cb]
+ */
+
 p.enter = function (op, cb) {
   this.cancelPending()
   this.callHook('beforeEnter')
@@ -44,6 +61,12 @@ p.enter = function (op, cb) {
   queue.push(this.nextEnter)
 }
 
+/**
+ * The "nextTick" phase of an entering transition, which is
+ * to be pushed into a queue and executed after a reflow so
+ * that removing the class can trigger a CSS transition.
+ */
+
 p.nextEnter = function () {
   var enterHook = this.hooks && this.hooks.enter
   var afterEnter = this.afterEnter
@@ -67,6 +90,10 @@ p.nextEnter = function () {
   }
 }
 
+/**
+ * The "cleanup" phase of an entering transition.
+ */
+
 p.afterEnter = function () {
   this.jsCancel = this.pendingJsCb = null
   removeClass(this.el, this.enterClass)
@@ -74,6 +101,13 @@ p.afterEnter = function () {
   if (this.cb) this.cb()
 }
 
+/**
+ * Start a leaving transition.
+ *
+ * @param {Function} op - remove/hide the element
+ * @param {Function} [cb]
+ */
+
 p.leave = function (op, cb) {
   this.cancelPending()
   this.callHook('beforeLeave')
@@ -95,6 +129,10 @@ p.leave = function (op, cb) {
   }
 }
 
+/**
+ * The "nextTick" phase of a leaving transition.
+ */
+
 p.nextLeave = function () {
   var type = this.getCssTransitionType(this.leaveClass)
   if (type) {
@@ -107,6 +145,10 @@ p.nextLeave = function () {
   }
 }
 
+/**
+ * The "cleanup" phase of a leaving transition.
+ */
+
 p.afterLeave = function () {
   this.op()
   removeClass(this.el, this.leaveClass)
@@ -114,6 +156,11 @@ p.afterLeave = function () {
   if (this.cb) this.cb()
 }
 
+/**
+ * Cancel any pending callbacks from a previously running
+ * but not finished transition.
+ */
+
 p.cancelPending = function () {
   this.op = this.cb = null
   var hasPending = false
@@ -137,12 +184,26 @@ p.cancelPending = function () {
   }
 }
 
+/**
+ * Call a user-provided hook function.
+ *
+ * @param {String} type
+ */
+
 p.callHook = function (type) {
   if (this.hooks && this.hooks[type]) {
     this.hooks[type].call(this.vm, this.el)
   }
 }
 
+/**
+ * Get an element's transition type based on the
+ * calculated styles.
+ *
+ * @param {String} className
+ * @return {Number}
+ */
+
 p.getCssTransitionType = function (className) {
   // skip CSS transitions if page is not visible -
   // this solves the issue of transitionend events not
@@ -175,6 +236,13 @@ p.getCssTransitionType = function (className) {
   return type
 }
 
+/**
+ * Setup a CSS transitionend/animationend callback.
+ *
+ * @param {String} event
+ * @param {Function} cb
+ */
+
 p.setupCssCb = function (event, cb) {
   this.pendingCssEvent = event
   var self = this