--- a/gfx/layers/AnimationHelper.h
+++ b/gfx/layers/AnimationHelper.h
@@ -68,18 +68,30 @@ struct AnimatedValue {
   }
 
   ~AnimatedValue() {}
 
 private:
   AnimatedValue() = delete;
 };
 
-// CompositorAnimationStorage stores the layer animations and animated value
-// after sampling based on an unique id (CompositorAnimationsId)
+// CompositorAnimationStorage stores the animations and animated values
+// keyed by a CompositorAnimationsId. The "animations" are a representation of
+// an entire animation over time, while the "animated values" are values sampled
+// from the animations at a particular point in time.
+//
+// There is one CompositorAnimationStorage per CompositorBridgeParent (i.e.
+// one per browser window), and the CompositorAnimationsId key is unique within
+// a particular CompositorAnimationStorage instance.
+//
+// Each layer which has animations gets a CompositorAnimationsId key, and reuses
+// that key during its lifetime. Likewise, in layers-free webrender, a display
+// item that is animated (e.g. nsDisplayTransform) gets a CompositorAnimationsId
+// key and reuses that key (it persists the key via the frame user-data
+// mechanism).
 class CompositorAnimationStorage final
 {
   typedef nsClassHashtable<nsUint64HashKey, AnimatedValue> AnimatedValueTable;
   typedef nsClassHashtable<nsUint64HashKey, AnimationArray> AnimationsTable;
 
   NS_INLINE_DECL_THREADSAFE_REFCOUNTING(CompositorAnimationStorage)
 public:
 
@@ -157,69 +169,66 @@ public:
   {
     return mAnimations.Count();
   }
 
   /**
    * Clear AnimatedValues and Animations data
    */
   void Clear();
+  void ClearById(const uint64_t& aId);
 
-  void ClearById(const uint64_t& aId);
 private:
   ~CompositorAnimationStorage() { };
 
 private:
   AnimatedValueTable mAnimatedValues;
   AnimationsTable mAnimations;
 };
 
+/**
+ * This utility class allows reusing code between the webrender and
+ * non-webrender compositor-side implementations. It provides
+ * utility functions for sampling animations at particular timestamps.
+ */
 class AnimationHelper
 {
 public:
 
-
-  /*
-   * TODO Bug 1356509 Once we decouple the compositor animations and layers
-   * in parent side, the API will be called inside SampleAnimations.
-   * Before this, we expose this API for AsyncCompositionManager.
-   *
+  /**
    * Sample animations based on a given time stamp for a element(layer) with
    * its animation data.
    * Returns true if there exists compositor animation, and stores corresponding
    * animated value in |aAnimationValue|.
    */
   static bool
   SampleAnimationForEachNode(TimeStamp aTime,
                              AnimationArray& aAnimations,
                              InfallibleTArray<AnimData>& aAnimationData,
                              StyleAnimationValue& aAnimationValue,
                              bool& aHasInEffectAnimations);
-  /*
-   * TODO Bug 1356509 Once we decouple the compositor animations and layers
-   * in parent side, the API will be called inside SampleAnimations.
-   * Before this, we expose this API for AsyncCompositionManager.
-   *
-   * Populates AnimData stuctures into |aAnimData| based on |aAnimations|
+  /**
+   * Populates AnimData stuctures into |aAnimData| and |aBaseAnimationStyle|
+   * based on |aAnimations|.
    */
   static void
   SetAnimations(AnimationArray& aAnimations,
                 InfallibleTArray<AnimData>& aAnimData,
                 StyleAnimationValue& aBaseAnimationStyle);
 
-  /*
+  /**
    * Get a unique id to represent the compositor animation between child
    * and parent side. This id will be used as a key to store animation
    * data in the CompositorAnimationStorage per compositor.
    * Each layer on the content side calls this when it gets new animation
    * data.
    */
   static uint64_t GetNextCompositorAnimationsId();
 
-  /*
+  /**
    * Sample animation based a given time stamp |aTime| and the animation
    * data inside CompositorAnimationStorage |aStorage|. The animated values
    * after sampling will be stored in CompositorAnimationStorage as well.
    */
   static void
   SampleAnimations(CompositorAnimationStorage* aStorage,
                    TimeStamp aTime);
 };

--- a/gfx/layers/ipc/CrossProcessCompositorBridgeParent.h
+++ b/gfx/layers/ipc/CrossProcessCompositorBridgeParent.h
@@ -9,17 +9,16 @@
 
 #include "mozilla/layers/CompositorBridgeParent.h"
 #include "mozilla/layers/CompositorThread.h"
 
 namespace mozilla {
 namespace layers {
 
 class CompositorOptions;
-class CompositorAnimationStorage;
 
 /**
  * This class handles layer updates pushed directly from child processes to
  * the compositor thread. It's associated with a CompositorBridgeParent on the
  * compositor thread. While it uses the PCompositorBridge protocol to manage
  * these updates, it doesn't actually drive compositing itself. For that it
  * hands off work to the CompositorBridgeParent it's associated with.
  */