Re-write docs for DlSkCanvas{Adapter|Dispatcher}.

display_list/skia/dl_sk_canvas.h

@@ -10,8 +10,12 @@
 
 namespace flutter {
 
-// An adapter to receive DlCanvas calls and dispatch them into
-// an SkCanvas.
+// -----------------------------------------------------------------------------
+/// @brief      A Canvas implementation that delegates to an Skia-backed Canvas.
+///
+/// This class is intended to be used an internal implementation detail for the
+/// DisplayList package. @see DlSkCanvasDispatcher for the developer-facing
+/// interface to Skia.
 class DlSkCanvasAdapter final : public virtual DlCanvas {
  public:
   DlSkCanvasAdapter() : delegate_(nullptr) {}

display_list/skia/dl_sk_dispatcher.h

@@ -14,11 +14,20 @@
 namespace flutter {
 
 //------------------------------------------------------------------------------
-/// Can be fed to the dispatch() method of a DisplayList to feed the resulting
-/// rendering operations to an SkCanvas instance.
+/// @brief      A Dispatcher that feeds rendering operations to an SkCanvas.
 ///
-/// Receives all methods on Dispatcher and sends them to an SkCanvas
+/// This class is intended to be used as the developer-facing interface to Skia
+/// (with the DisplayList abstraction allowing different backends to be used,
+/// such as Impeller).
 ///
+/// @note       This class has contains clip and transform state (to know the
+///             transform or combined clip at any given operation, the clip and
+///             transform state is tracked within).
+///
+///             Paint attributes in general are stateful; each "setX" method
+///             stores a persistent value for the ttribute for the rest of the
+///             display list or until it is reset by another method that changes
+///             the same attribute.
 class DlSkCanvasDispatcher : public virtual DlOpReceiver,
                              public DlSkPaintDispatchHelper {
  public: