From d399a6b19449a207b8f429753543a45a980614bf Mon Sep 17 00:00:00 2001
From: "Alex A. Naanou" <alex.nanou@gmail.com>
Date: Mon, 24 Nov 2014 08:15:19 +0300
Subject: [PATCH] added docs to transition prevention API...

Signed-off-by: Alex A. Naanou <alex.nanou@gmail.com>
---
 ui (gen4)/ribbons.js | 51 +++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 50 insertions(+), 1 deletion(-)

diff --git a/ui (gen4)/ribbons.js b/ui (gen4)/ribbons.js
index 39185c9e..711f68ac 100755
--- a/ui (gen4)/ribbons.js	
+++ b/ui (gen4)/ribbons.js	
@@ -135,7 +135,26 @@ var RibbonsPrototype = {
 
 	// Helpers...
 
-	// XXX need a better way of doing this...
+	// Prevent CSS transitions...
+	//
+	// 	Prevent transitions globally (.viewer):
+	// 	.preventTransitions()
+	// 		-> data
+	//
+	// 	Prevent transitions on elem:
+	// 	.preventTransitions(elem)
+	// 		-> data
+	//
+	// 	Prevent transitions on this and all nested calls
+	// 	.preventTransitions(.., true)
+	// 		-> data
+	//
+	// 		NOTE: all *nested* calls to this and .restoreTransitions(..)
+	// 			will be ignored.
+	//
+	// NOTE: this will set a .no-transitions CSS class and force 
+	// 		recalculation on the given element
+	// NOTE: for this to have effect proper CSS configuration is needed.
 	preventTransitions: function(target, prevent_nested){
 		target = target || this.viewer
 		prevent_nested = prevent_nested || false
@@ -164,6 +183,32 @@ var RibbonsPrototype = {
 
 		return this
 	},
+
+	// Prevent CSS transitions...
+	//
+	// This is a companion to .preventTransitions(..)
+	//
+	// 	Restore transitions globally (.viewer):
+	// 	.restoreTransitions()
+	// 		-> data
+	//
+	// 	Restore transitions on elem: 
+	// 	.restoreTransitions(elem)
+	// 		-> data
+	//
+	// 	Restore transitions on elem (force sync): 
+	// 	.restoreTransitions(elem, true)
+	// 		-> data
+	//
+	// 	Force restore transitions: 
+	// 	.restoreTransitions(.., .., true)
+	// 		-> data
+	//
+	// When at least one .preventTransitions(..) is called with 
+	// prevent_nested set to true, this will be a no-op on all nested
+	// levels.
+	// This can be overridden via setting the force to true.
+	//
 	restoreTransitions: function(target, now, force){
 		if(target === true || target === false){
 			now = target
@@ -209,6 +254,10 @@ var RibbonsPrototype = {
 
 		return this
 	},
+
+	// Shorthand wrappers of the above...
+	//
+	// XXX do we need custom target support here???
 	noTransitions: function(func){
 		this.preventTransitions()
 		func.apply(this, args2array(arguments).slice(1))