Re-write docs for DlSkCanvas{Adapter|Dispatcher}. (#44961)

Closes flutter/flutter#132994.

I suspect this is imperfect, so please suggest any changes or additions (either using GitHub's tooling or as a review comment).

/cc @dnfield

Author: matanlurey

display_list/dl_canvas.h

@@ -20,16 +20,18 @@
 
 namespace flutter {
 
-// The primary class used to express rendering operations in the
-// DisplayList ecosystem. This class is an API-only virtual class and
-// can be used to talk to a DisplayListBuilder to record a series of
-// rendering operations, or it could be the public facing API of an
-// adapter that forwards the calls to another rendering module, like
-// Skia.
-//
-// Developers familiar with Skia's SkCanvas API will be immediately
-// familiar with the methods below as they follow that API closely
-// but with DisplayList objects and values used as data instead.
+//------------------------------------------------------------------------------
+/// @brief    Developer-facing API for rendering anything *within* the engine.
+///
+/// |DlCanvas| should be used to render anything in the framework classes (i.e.
+/// `lib/ui`), flow and flow layers, embedders, shell, and elsewhere.
+///
+/// The only state carried by implementations of this interface are the clip
+/// and transform which are saved and restored by the |save|, |saveLayer|, and
+/// |restore| calls.
+///
+/// @note      The interface resembles closely the familiar |SkCanvas| interface
+///            used throughout the engine.
 class DlCanvas {
  public:
   enum class ClipOp {

display_list/dl_op_receiver.h

@@ -23,11 +23,22 @@ namespace flutter {
 class DisplayList;
 
 //------------------------------------------------------------------------------
-/// @brief      The pure virtual interface for interacting with a display list.
-///             This interface represents the methods used to build a list
-///             through the DisplayListBuilder and also the methods that will be
-///             invoked through the DisplayList::dispatch() method.
+/// @brief      Internal API for rendering recorded display lists to backends.
 ///
+/// The |DisplayList| object will play back recorded operations in this format.
+/// Most developers should not need to deal with this interface unless they are
+/// writing a utility that needs to examine the contents of a display list.
+///
+/// Similar to |DlCanvas|, this interface carries clip and transform state
+/// which are saved and restored by the |save|, |saveLayer|, and |restore|
+/// calls.
+///
+/// Unlike DlCanvas, this interface has attribute state which is global across
+/// an entire DisplayList (not affected by save/restore).
+///
+/// @see        DlSkCanvasDispatcher
+/// @see        impeller::DlDispatcher
+/// @see        DlOpSpy
 class DlOpReceiver {
  protected:
   using ClipOp = DlCanvas::ClipOp;

display_list/skia/dl_sk_canvas.h

@@ -10,8 +10,10 @@
 
 namespace flutter {
 
-// An adapter to receive DlCanvas calls and dispatch them into
-// an SkCanvas.
+// -----------------------------------------------------------------------------
+/// @brief      Backend implementation of |DlCanvas| for |SkCanvas|.
+///
+/// @see        DlCanvas
 class DlSkCanvasAdapter final : public virtual DlCanvas {
  public:
   DlSkCanvasAdapter() : delegate_(nullptr) {}

display_list/skia/dl_sk_dispatcher.h

@@ -14,11 +14,9 @@
 namespace flutter {
 
 //------------------------------------------------------------------------------
-/// Can be fed to the dispatch() method of a DisplayList to feed the resulting
-/// rendering operations to an SkCanvas instance.
-///
-/// Receives all methods on Dispatcher and sends them to an SkCanvas
+/// @brief      Backend implementation of |DlOpReceiver| for |SkCanvas|.
 ///
+/// @see       DlOpReceiver
 class DlSkCanvasDispatcher : public virtual DlOpReceiver,
                              public DlSkPaintDispatchHelper {
  public: