Add documentation to scroll animator classes.

Bug: 740070
Cq-Include-Trybots: master.tryserver.blink:linux_trusty_blink_rel
Change-Id: I3b4b73df9598d474af0e6f36494b06c54bbdde2a
Reviewed-on: https://chromium-review.googlesource.com/578658
Commit-Queue: Steve Kobes <skobes@chromium.org>
Reviewed-by: Walter Korman <wkorman@chromium.org>
Reviewed-by: Alexandre Elias <aelias@chromium.org>
Reviewed-by: Philip Rogers <pdr@chromium.org>
Cr-Commit-Position: refs/heads/master@{#488838}

cc/animation/scroll_offset_animation_curve.h

@@ -17,9 +17,27 @@ namespace cc {
 
 class TimingFunction;
 
+// ScrollOffsetAnimationCurve computes scroll offset as a function of time
+// during a scroll offset animation.
+//
+// Scroll offset animations can run either in Blink or on a cc AnimationPlayer,
+// in response to user input or programmatic scroll operations.  For more
+// information about scheduling and servicing scroll animations, see
+// blink::ScrollAnimator and blink::ProgrammaticScrollAnimator.
+
 class CC_ANIMATION_EXPORT ScrollOffsetAnimationCurve : public AnimationCurve {
  public:
-  enum class DurationBehavior { DELTA_BASED, CONSTANT, INVERSE_DELTA };
+  // Indicates how the animation duration should be computed.
+  enum class DurationBehavior {
+    // Duration proportional to scroll delta; used for programmatic scrolls.
+    DELTA_BASED,
+    // Constant duration; used for keyboard scrolls.
+    CONSTANT,
+    // Duration inversely proportional to scroll delta within certain bounds.
+    // Used for mouse wheels, makes fast wheel flings feel "snappy" while
+    // preserving smoothness of slow wheel movements.
+    INVERSE_DELTA
+  };
   static std::unique_ptr<ScrollOffsetAnimationCurve> Create(
       const gfx::ScrollOffset& target_value,
       std::unique_ptr<TimingFunction> timing_function,
@@ -36,7 +54,16 @@ class CC_ANIMATION_EXPORT ScrollOffsetAnimationCurve : public AnimationCurve {
   bool HasSetInitialValue() const;
   gfx::ScrollOffset GetValue(base::TimeDelta t) const;
   gfx::ScrollOffset target_value() const { return target_value_; }
+
+  // Updates the current curve to aim at a new target, starting at time t
+  // relative to the start of the animation.  The duration is recomputed based
+  // on the DurationBehavior the curve was constructed with.  The timing
+  // function is an ease-in-out cubic bezier modified to preserve velocity at t.
   void UpdateTarget(double t, const gfx::ScrollOffset& new_target);
+
+  // Shifts the entire curve by a delta without affecting its shape or timing.
+  // Used for scroll anchoring adjustments that happen during scroll animations
+  // (see blink::ScrollAnimator::AdjustAnimationAndSetScrollOffset).
   void ApplyAdjustment(const gfx::Vector2dF& adjustment);
 
   // AnimationCurve implementation

third_party/WebKit/Source/platform/mac/ScrollAnimatorMac.h

@@ -46,6 +46,49 @@ namespace blink {
 
 class Scrollbar;
 
+// ScrollAnimatorMac implements keyboard-triggered scroll offset animations,
+// scrollbar painting, and scrollbar opacity animations by delegating to native
+// Cocoa APIs.
+//
+// Scroll offset animations are also known as "smooth scrolling".  For the
+// non-Mac implementation of user input smooth scrolling, see ScrollAnimator.
+// For programmatic (CSSOM) smooth scrolls, see ProgrammaticScrollAnimator.
+//
+// Unlike ScrollAnimator, ScrollAnimatorMac only smooth-scrolls keyboard
+// scrolls, and not mouse wheel scrolls.  It also does not use compositor
+// animations or any of the standard Blink animation machinery.
+//
+// This divergence is mostly historical.  We could probably switch Mac to use
+// ScrollAnimator for smooth scrolls if we factored out the scrollbar-related
+// logic.  See crbug.com/574283 and crbug.com/682209.
+//
+// ScrollAnimatorMac's scroll offset animations are implemented by
+// NSScrollAnimationHelper which invokes a BlinkScrollAnimationHelperDelegate to
+// service an animation frame by performing an immediate scroll to the requested
+// offset (via NotifyOffsetChanged).
+//
+// The "scrollbar painter controller" is an NSScrollerImpPair object, which
+// calls back into Blink via BlinkScrollbarPainterControllerDelegate.
+//
+// The "scrollbar painter" is an NSScrollerImp object, which calls back into
+// Blink via BlinkScrollbarPainterDelegate.  The scrollbar painter is registered
+// with ScrollbarThemeMac, so that the ScrollbarTheme painting APIs can call
+// into it.
+//
+// The scrollbar painter initiates an overlay scrollbar fade-out animation by
+// calling animateKnobAlphaTo on the delegate.  This starts a timer inside the
+// BlinkScrollbarPartAnimationTimer.  Each tick evaluates a cubic bezier
+// function to obtain the current opacity, which is stored in the scrollbar
+// painter with setKnobAlpha.
+//
+// If the scroller is composited, the opacity value stored on the scrollbar
+// painter is subsequently read out through ScrollbarThemeMac::ThumbOpacity and
+// plumbed into PaintedScrollbarLayerImpl::thumb_opacity_.
+//
+// TODO: explain other types of animations (TrackAlpha, UIStateTransition,
+// ExpansionTransition), scrollbar paint timer, plumbing of scrollbar paint
+// invalidations.
+
 class PLATFORM_EXPORT ScrollAnimatorMac : public ScrollAnimatorBase {
   USING_PRE_FINALIZER(ScrollAnimatorMac, Dispose);
 

third_party/WebKit/Source/platform/scroll/ProgrammaticScrollAnimator.h

@@ -17,8 +17,13 @@ class ScrollableArea;
 class CompositorAnimationTimeline;
 class CompositorScrollOffsetAnimationCurve;
 
-// Animator for fixed-destination scrolls, such as those triggered by
-// CSSOM View scroll APIs.
+// ProgrammaticScrollAnimator manages scroll offset animations ("smooth
+// scrolls") triggered by web APIs such as "scroll-behavior: smooth" which are
+// standardized by the CSSOM View Module (https://www.w3.org/TR/cssom-view-1/).
+//
+// For scroll animations triggered by user input, see ScrollAnimator and
+// ScrollAnimatorMac.
+
 class ProgrammaticScrollAnimator : public ScrollAnimatorCompositorCoordinator {
   WTF_MAKE_NONCOPYABLE(ProgrammaticScrollAnimator);
 

third_party/WebKit/Source/platform/scroll/ScrollAnimator.h

@@ -42,6 +42,61 @@ namespace blink {
 
 class CompositorAnimationTimeline;
 
+// ScrollAnimator is the Blink-side implementation of user-input scroll offset
+// animations ("smooth scrolling") on all platforms except for Mac.
+//
+// See http://bit.ly/smoothscrolling for general info about user-input smooth
+// scrolling.  For the Mac implementation, see ScrollAnimatorMac.  For
+// programmatic (CSSOM) smooth scrolls, see ProgrammaticScrollAnimator.
+//
+// When Blink receives an input event that should start or update a scroll
+// animation, it calls ScrollAnimator::UserScroll.  This will construct an
+// animation curve object which can report the desired scroll offset as a
+// function of elapsed time.  See cc/animation/scroll_offset_animation_curve.h
+// for more info about the animation curve logic (including velocity-matched
+// target updating).
+//
+// Having established an animation curve, the logic for servicing the animation
+// is highly dependent on compositing.  There are four scenarios to consider:
+//
+// (1) Scroll animation running on the compositor, scheduled by the compositor
+//     (LayerTreeHostImpl::ScrollAnimated) in response to a scroll wheel input
+//     event handled by the compositor thread.  Blink doesn't know about these.
+//
+// (2) Scroll animation running on the compositor, scheduled by Blink.  For
+//     example, a keyboard scroll of a composited scroller.
+//
+// (3) Scroll animation of a composited scroller, running on the main thread due
+//     to main-thread scrolling reasons (for example, non-composited fixed-
+//     position elements that need to be repainted on scroll).
+//
+// (4) Scroll animation of a non-composited scroller, running on the main
+//     thread.
+//
+// In scenarios (1) and (2) the animation is created as a cc::Animation with
+// TargetProperty::SCROLL_OFFSET and added to a cc::AnimationPlayer that is
+// serviced on the compositor thread (in cc::AnimationHost::TickAnimations).
+// This lets the animation play smoothly even if the main thread is janked.
+//
+// In scenarios (3) and (4), we schedule the animation ticks on the main thread
+// using ScrollableArea::ScheduleAnimation, and update the scroll offset during
+// ScrollAnimator::TickAnimation.
+//
+// There is a special main-thread scrolling reason kHandlingScrollFromMainThread
+// set in scenarios (2) and (3) for the duration of the scroll, to prevent
+// interference from events that would otherwise trigger scenario (1).
+//
+// There is a complicated handoff from (1) to (3) in the event that a main-
+// thread scrolling reason is added in the middle of an animation.  This is
+// handled by TakeOverCompositorAnimation, which aborts the animation in cc and
+// sends an AnimationEvent::TAKEOVER back to the main thread containing a copy
+// of the curve.  That calls back into NotifyAnimationTakeover which starts a
+// new animation on main to play the "remainder" of the curve.
+//
+// The logic for Blink-side scheduling of compositor-serviced scroll offset
+// animations is shared with ProgrammaticScrollAnimator, and lives mostly in the
+// common base class ScrollAnimatorCompositorCoordinator.
+
 class PLATFORM_EXPORT ScrollAnimator : public ScrollAnimatorBase {
  public:
   explicit ScrollAnimator(ScrollableArea*,

third_party/WebKit/Source/platform/scroll/ScrollAnimatorBase.h

@@ -43,6 +43,13 @@ class CompositorAnimationTimeline;
 class ScrollableArea;
 class Scrollbar;
 
+// ScrollAnimatorBase is the common base class for all user scroll animators.
+// Every scrollable area has a lazily-created animator for user-input scrolls
+// (ScrollableArea::scroll_animator_).
+//
+// ScrollAnimatorBase is directly instantiated when scroll animations are
+// disabled.  In this case, all scrolls are instantaneous.
+
 class PLATFORM_EXPORT ScrollAnimatorBase
     : public ScrollAnimatorCompositorCoordinator {
  public:

third_party/WebKit/Source/platform/scroll/ScrollAnimatorCompositorCoordinator.h

@@ -25,6 +25,12 @@ class CompositorAnimation;
 class CompositorAnimationPlayer;
 class CompositorAnimationTimeline;
 
+// ScrollAnimatorCompositorCoordinator is the common base class of user scroll
+// animators and programmatic scroll animators, and holds logic related to
+// scheduling and updating scroll animations running on the compositor.
+//
+// See ScrollAnimator.h for more information about scroll animations.
+
 class PLATFORM_EXPORT ScrollAnimatorCompositorCoordinator
     : public GarbageCollectedFinalized<ScrollAnimatorCompositorCoordinator>,
       private CompositorAnimationPlayerClient,