It's a start. It might be worth mentioning the odd stateful nature of the paint attributes which I don't think DlOpReceiver really describes in much detail. There is a short description in that interface right before all of the setFoo() attribute setters, but it should be called out in the "class comment" and we should also point out that they persist through and beyond save/restore calls unlike the clip and transform state.

Added a note!

Class comment for DlCanvas in dl_canvas.h should be something like:

This is the engine developer facing API for rendering anything within the engine. It should be the API used to render anything in the framework classes (lib/ui), flow and flow/layers, embedders, shell, etc.

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. (possibly explain that in more detail if you think it needs it)

The interface resembles closely the familiar SkCanvas interface that was used throughout the engine.

see DlSkAdapter(sp?)
see impeller::class that Dan is working on?

Then DlOpReceiver in dl_op_receiver.h should be something like:

This is an internal implementation interface for rendering backends that need to interact with recorded display lists. The DisplayList object will play back recorded operations in this format. Most developers should not needed to deal with this interface unless they are writing a utility that needs to examine the contents of a display list.

[Mention that it also has the same clip/transform state as DlCanvas, and...]
[Description of attribute state]

see DlSkDispatcher(sp?)
see impeller::DlDispatcher(sp?)
see DlOpSpy

DlSk* are only implementations, they shouldn't be the place where we document these interfaces. They should simply point people to the DlCanvas or DlOpReceiver interfaces and mention that they are the Skia-specific implementation of those interface classes...

Tried my best :), feel free to point out anything additional!