Added class docstrings for classes inside of shell/common.

shell/common/animator.h

@@ -22,6 +22,10 @@ namespace testing {
 class ShellTest;
 }
 
+/// Executor of animations.
+///
+/// In conjunction with the |VsyncWaiter| it allows callers (typically Dart
+/// code) to schedule work that ends up generating a |LayerTree|.
 class Animator final {
  public:
   class Delegate {

shell/common/engine.h

@@ -29,6 +29,9 @@
 
 namespace flutter {
 
+/// Manager of the root Dart isolate and the relay of platform messages.
+///
+/// Also setups up dart::ui bindings and handles restarts.
 class Engine final : public RuntimeDelegate {
  public:
   // Used by Engine::Run

shell/common/isolate_configuration.h

@@ -19,6 +19,7 @@
 
 namespace flutter {
 
+/// Abstract Base Class that will configure a |DartIsolate|.
 class IsolateConfiguration {
  public:
   static std::unique_ptr<IsolateConfiguration> InferFromSettings(

shell/common/persistent_cache.h

@@ -17,6 +17,9 @@
 
 namespace flutter {
 
+/// A cache of SkData that gets stored to disk.
+///
+/// This is mainly used for Shaders but is also written to by Dart.
 class PersistentCache : public GrContextOptions::PersistentCache {
  public:
   // Mutable static switch that can be set before GetCacheForProcess. If true,

shell/common/pipeline.h

@@ -24,6 +24,8 @@ enum class PipelineConsumeResult {
 
 size_t GetNextPipelineTraceID();
 
+/// A thread-safe queue of resources for a single consumer and a single
+/// producer.
 template <class R>
 class Pipeline : public fml::RefCountedThreadSafe<Pipeline<R>> {
  public:

shell/common/platform_view.h

@@ -25,6 +25,8 @@ namespace flutter {
 
 class Shell;
 
+/// Abstract Base Class that represents the platform specific view we will be
+/// rendering to.
 class PlatformView {
  public:
   class Delegate {

shell/common/rasterizer.h

@@ -20,6 +20,7 @@
 
 namespace flutter {
 
+/// Takes |LayerTree|s and draws its contents.
 class Rasterizer final : public SnapshotDelegate {
  public:
   class Delegate {

shell/common/run_configuration.h

@@ -18,6 +18,9 @@
 
 namespace flutter {
 
+/// Configuration pertaining to how we will execute the Dart code.
+///
+/// For example: what will be the first function we execute (entrypoint).
 class RunConfiguration {
  public:
   static RunConfiguration InferFromSettings(

shell/common/shell.h

@@ -34,6 +34,8 @@
 
 namespace flutter {
 
+/// Wraps up all the different components of Flutter engine and coordinates them
+/// through a series of delegates.
 class Shell final : public PlatformView::Delegate,
                     public Animator::Delegate,
                     public Engine::Delegate,

shell/common/surface.h

@@ -41,6 +41,7 @@ class SurfaceFrame {
   FML_DISALLOW_COPY_AND_ASSIGN(SurfaceFrame);
 };
 
+/// Abstract Base Class that represents where we will be rendering content.
 class Surface {
  public:
   Surface();

shell/common/thread_host.h

@@ -12,6 +12,7 @@
 
 namespace flutter {
 
+/// The collection of all the threads used by the engine.
 struct ThreadHost {
   enum Type {
     Platform = 1 << 0,

shell/common/vsync_waiter.h

@@ -15,6 +15,8 @@
 
 namespace flutter {
 
+/// Abstract Base Class that represents a platform specific mechanism for
+/// getting callbacks when a vsync event happens.
 class VsyncWaiter : public std::enable_shared_from_this<VsyncWaiter> {
  public:
   using Callback = std::function<void(fml::TimePoint frame_start_time,

shell/common/vsync_waiter_fallback.h

@@ -12,6 +12,7 @@
 
 namespace flutter {
 
+/// A |VsyncWaiter| that will fire at 60 fps irrespective of the vsync.
 class VsyncWaiterFallback final : public VsyncWaiter {
  public:
   VsyncWaiterFallback(TaskRunners task_runners);