docs: Update animation section

Replace the existing Tweener section with a small outline of the
Clutter animation API and our wrappers.

https://gitlab.gnome.org/GNOME/gnome-shell/merge_requests/669

HACKING.md

@@ -84,7 +84,6 @@ don't use.
 
     const Main = imports.ui.main;
     const Params = imports.misc.params;
-    const Tweener = imports.ui.tweener;
     const Util = imports.misc.util;
 ```
 The alphabetical ordering should be done independently of the location of the
@@ -277,34 +276,49 @@ If your usage of an object is like a hash table (and thus conceptually the keys
 can have special chars in them), don't use quotes, but use brackets: `{ bar: 42
 }`, `foo['bar']`.
 
-## Getters, setters, and Tweener
+## Animations
+
+Most objects that are animated are actors, and most properties used in animations
+are animatable, which means they can use implicit animations:
 
-Getters and setters should be used when you are dealing with an API that is
-designed around setting properties, like Tweener. If you want to animate an
-arbitrary property, create a getter and setter, and use Tweener to animate the
-property.
 ```javascript
-    var ANIMATION_TIME = 2000;
+    moveActor(actor, x, y) {
-
+        actor.ease({
-    var MyClass = class {
+            x,
-        constructor() {
+            y,
-            this.actor = new St.BoxLayout();
+            duration: 500, // ms
-            this._position = 0;
+            mode: Clutter.AnimationMode.EASE_OUT_QUAD
-        }
+        });
-
+    }
-        get position() {
+```
-            return this._position;
+
-        }
+The above is a convenience wrapper around the actual Clutter API, and should generally
-
+be preferred over the more verbose:
-        set position(value) {
+
-            this._position = value;
+```javascript
-            this.actor.set_position(value, value);
+    moveActor(actor, x, y) {
-        }
+        actor.save_easing_state();
-    };
+
-
+        actor.set_easing_duration(500);
-    let myThing = new MyClass();
+        actor.set_easing_mode(Clutter.AnimationMode.EASE_OUT_QUAD);
-    Tweener.addTween(myThing,
+        actor.set({
-                     { position: 100,
+            x,
-                       time: ANIMATION_TIME,
+            y
-                       transition: 'easeOutQuad' });
+        });
+
+        actor.restore_easing_state();
+    }
+```
+
+There is a similar convenience API around Clutter.PropertyTransition to animate
+actor (or actor meta) properties that cannot use implicit animations:
+
+```javascript
+    desaturateActor(actor, desaturate) {
+        let factor = desaturate ? 1.0 : 0.0;
+        actor.ease_property('@effects.desaturate.factor', factor, {
+            duration: 500, // ms
+            mode: Clutter.AnimationMode.EASE_OUT_QUAD
+        });
+    }
 ```