MD Settings: Custom expand/collapse section animations.

third_party/closure_compiler/externs/web_animations.js

+// Copyright 2016 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+/**
+ * @fileoverview Minimal Closure externs for Web Animations.
+ * "Minimal" because the web-animations spec is in flux, Chromium's support is
+ * changing, and the intended consumer (MD Settings) is actually using the
+ * web-animations-js polyfill for the time being.

[Dan Beam, 2016/03/14 21:27:53]

can you add @see <link> for this file and any part that has an easily-accessible
link?

an example of this for the whole file would be

+ * @see https://w3c.github.io/web-animations/#programming-interface

[michaelpg, 2016/03/15 00:06:50]

Done.

+ */
+
+/**
+ * @enum {number}
+ */

[Dan Beam, 2016/03/14 21:27:53]

nit: almost all of these short jsdoc comments can be /** one-liners */

[michaelpg, 2016/03/15 00:06:50]

Done.

+var FillMode = {
+  'none': 0,
+  'forwards': 1,
+  'backwards': 2,
+  'both': 3,
+  'auto': 4
+};
+
+/**
+ * @enum {number}
+ */
+var PlaybackDirection = {
+  'normal': 0,
+  'reverse': 1,
+  'alternate': 2,
+  'alternate-reverse': 3
+};
+
+/**
+ * @constructor
+ * @param {!Event} event
+ */
+var EventHandlerNonNull = function(event) {};
+
+/**
+ * @typedef {?EventHandlerNonNull}
+ */
+var EventHandler;
+
+/**
+ * @constructor
+ */
+var KeyframeAnimationOptions = function() {};
+
+/**
+ * @constructor
+ */
+var KeyframeEffectOptions = function() {};
+
+/**
+ * @type {number}
+ */
+KeyframeEffectOptions.prototype.delay = 0;

[Dan Beam, 2016/03/14 21:27:53]

one advantage of the .prototype.* route is that you don't have to initialize
each property (and probably shouldn't be):

  KeyframeEffectOptions.prototype.delay = 0;

would become just:

  KeyframeEffectOptions.prototype.delay;

with @type.

note: I have been asked by ewa@ and other externs reviewers to explicitly NOT
use sane default values in externs, as well as I know that all of this JS still
needs to be parsed (even though it's moved to a different AST), and adding these
values may slightly slow that down.

[michaelpg, 2016/03/15 00:06:50]

Ok, but then why not extend this logic to functions?

    /** @constructor **
    var KeyframeEffectOptions;

    /** @type {function()} */
    Animation.prototype.finish;

etc.

[Dan Beam, 2016/03/16 00:23:14]

suppose that's OK, too, as long as you can name and describe @param's (can you?)

[michaelpg, 2016/03/16 03:11:15]

Yeah it seems to work just the same. I'll keep it the "usual" way though.

+
+/**
+ * @type {number}
+ */
+KeyframeEffectOptions.prototype.endDelay = 0;
+
+/**
+ * @type {!FillMode}
+ */
+KeyframeEffectOptions.prototype.fill = FillMode.auto;
+
+/**
+ * @type {number}
+ */
+KeyframeEffectOptions.prototype.iterationStart = 0;
+
+/**
+ * @type {number}
+ */
+KeyframeEffectOptions.prototype.iterations = 1;
+
+/**
+ * @type {number|string}
+ */
+KeyframeEffectOptions.prototype.duration = 'auto';
+
+/**
+ * @type {number}
+ */
+KeyframeEffectOptions.prototype.playbackRate = 1;
+
+/**
+ * @type {!PlaybackDirection}
+ */
+KeyframeEffectOptions.prototype.direction = PlaybackDirection.normal;
+
+/**
+ * @type {string}
+ */
+KeyframeEffectOptions.prototype.easing = 'linear';
+
+/**
+ * @type {string}
+ */
+KeyframeEffectOptions.prototype.id = '';
+
+/**
+ * @interface
+ * @extends {EventTarget}
+ */
+var Animation = function() {};
+
+/**
+ * @type {string}
+ */
+Animation.prototype.id;
+
+/**
+ * @type {?number}
+ */
+Animation.prototype.startTime;
+
+/**
+ * @type {?number}
+ */
+Animation.prototype.currentTime;
+
+/**
+ * @type {number}
+ */
+Animation.prototype.playbackRate;
+
+Animation.prototype.finish = function() {};
+
+Animation.prototype.play = function() {};
+
+Animation.prototype.pause = function() {};
+
+Animation.prototype.reverse = function() {};
+
+Animation.prototype.cancel = function() {};
+
+/**
+ * @param {boolean=} opt_useCapture
+ * @override
+ */
+Animation.prototype.addEventListener = function(
+    type, listener, opt_useCapture) {};
+
+/**
+ * @type {EventHandler}
+ */
+Animation.prototype.onfinish;
+
+/**
+ * @type {EventHandler}
+ */
+Animation.prototype.oncancel;
+
+/**
+ * @interface
+ */
+function Animatable() {};

[Dan Beam, 2016/03/14 21:27:53]

no ;

[michaelpg, 2016/03/15 00:06:50]

Done.

+
+Animatable.prototype = /** @lends {Element.prototype} */({

[Dan Beam, 2016/03/14 21:27:53]

til: @lends is a thing

+  /**
+   * @param {?Array<Object>|Object} effect
+   * @param {number|!KeyframeEffectOptions=} opt_timing
+   * @return {!Animation}
+   */
+  animate: function(effect, opt_timing) {},
+});