From 254401dca0bcd7cb6caa41f9c0386fe70540dc8b Mon Sep 17 00:00:00 2001
From: Matan Lurey <matanlurey@users.noreply.github.com>
Date: Mon, 28 Aug 2023 13:06:14 -0700
Subject: [PATCH] Re-write docs for DlSkCanvas{Adapter|Dispatcher}.
 (flutter/engine#44961)

Closes https://github.com/flutter/flutter/issues/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
---
 engine/src/flutter/display_list/dl_canvas.h   | 22 ++++++++++---------
 .../src/flutter/display_list/dl_op_receiver.h | 19 ++++++++++++----
 .../flutter/display_list/skia/dl_sk_canvas.h  |  6 +++--
 .../display_list/skia/dl_sk_dispatcher.h      |  6 ++---
 4 files changed, 33 insertions(+), 20 deletions(-)

diff --git a/engine/src/flutter/display_list/dl_canvas.h b/engine/src/flutter/display_list/dl_canvas.h
index 8fad40d234..f04645c157 100644
--- a/engine/src/flutter/display_list/dl_canvas.h
+++ b/engine/src/flutter/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 {
diff --git a/engine/src/flutter/display_list/dl_op_receiver.h b/engine/src/flutter/display_list/dl_op_receiver.h
index 36bdaef69c..1fe13c6f84 100644
--- a/engine/src/flutter/display_list/dl_op_receiver.h
+++ b/engine/src/flutter/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;
diff --git a/engine/src/flutter/display_list/skia/dl_sk_canvas.h b/engine/src/flutter/display_list/skia/dl_sk_canvas.h
index af774b7434..0377b7de75 100644
--- a/engine/src/flutter/display_list/skia/dl_sk_canvas.h
+++ b/engine/src/flutter/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) {}
diff --git a/engine/src/flutter/display_list/skia/dl_sk_dispatcher.h b/engine/src/flutter/display_list/skia/dl_sk_dispatcher.h
index 3ae3217002..a5356f5075 100644
--- a/engine/src/flutter/display_list/skia/dl_sk_dispatcher.h
+++ b/engine/src/flutter/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: