polish picture and rrect docs

TBR=caryclark@google.com

Docs-Preview: https://skia.org/?cl=141263
Bug: skia:6818
Change-Id: I33a197892b3dd5788499dda9dd9e95ddab861388
Reviewed-on: https://skia-review.googlesource.com/141263
Commit-Queue: Cary Clark <caryclark@skia.org>
Auto-Submit: Cary Clark <caryclark@skia.org>
Reviewed-by: Cary Clark <caryclark@skia.org>

13 files changed, 151 insertions, 103 deletions

diff --git a/docs/SkPicture_Reference.bmh b/docs/SkPicture_Reference.bmh
index 64561de50e..8ad642aa73 100644
--- a/docs/SkPicture_Reference.bmh
+++ b/docs/SkPicture_Reference.bmh
@@ -4,8 +4,16 @@
 
 #Class SkPicture
 
-An SkPicture records drawing commands made to a canvas to be played back at a later time.
-This base class handles serialization and a few other miscellany.
+Picture records drawing commands made to Canvas. The command stream may be
+played in whole or in part at a later time.
+
+Picture is an abstract class. Picture may be generated by Picture_Recorder
+or Drawable, or from Picture previously saved to Data or Stream. 
+
+Picture may contain any Canvas drawing command, as well as one or more
+Canvas_Matrix or Canvas_Clip. Picture has a cull Rect, which is used as
+a bounding box hint. To limit Picture bounds, use Canvas_Clip when
+recording or drawing Picture.
 
 #Subtopic Overview
 #Populate
@@ -33,13 +41,11 @@ This base class handles serialization and a few other miscellany.
     };
 ##
 
-Subclasses of this can be passed to playback(). During the playback
-of the picture, this callback will periodically be invoked. If its
-abort() returns true, then picture playback will be interrupted.
-The resulting drawing is undefined, as there is no guarantee how often the
-callback will be invoked. If the abort happens inside some level of nested
-calls to save(), restore will automatically be called to return the state
-to the same level it was before the playback call was made.
+AbortCallback is an abstract class. An implementation of AbortCallback may
+passed as a parameter to SkPicture::playback, to stop it before all drawing
+commands have been processed.
+
+If AbortCallback::abort returns true, SkPicture::playback is interrupted.
 
 # ------------------------------------------------------------------------------
 
@@ -78,8 +84,14 @@ Has no effect.
 #Line # aborts playback by callback ##
 
 Stops Picture playback when some condition is met. A subclass of
-AbortCallback provides an override for abort() that can stop playback() from
-drawing the entire picture.
+AbortCallback provides an override for abort() that can stop SkPicture::playback.
+
+The part of Picture drawn when aborted is undefined. Picture instantiations are
+free to stop drawing at different points during playback.
+
+If the abort happens inside one or more calls to SkCanvas::save(), stack
+of Canvas_Matrix and Canvas_Clip values is restored to its state before
+SkPicture::playback was called.
 
 #Return true to stop playback ##
 
@@ -224,10 +236,11 @@ Recreates a picture that was serialized into data.
 #In Action
 #Line # replays drawing commands on canvas ##
 
-Replays the drawing commands on the specified canvas. Note that
-this has the effect of unfurling this picture into the destination
-canvas. Using the SkCanvas::drawPicture entry point gives the destination
-canvas the option of just taking a ref.
+Replays the drawing commands on the specified canvas. In the case that the
+commands are recorded, each command in the Picture is sent separately to canvas.
+
+To add a single command to draw Picture to recording canvas, call
+SkCanvas::drawPicture instead.
 
 #Param canvas  receiver of drawing commands ##
 #Param callback  allows interruption of playback ##
@@ -253,8 +266,12 @@ canvas the option of just taking a ref.
 #In Property
 #Line # returns bounds used to record Picture ##
 
-Returns cull Rect for this picture.
-Ops recorded into this picture that attempt to draw outside the cull might not be drawn.
+Returns cull Rect for this picture, passed in when Picture was created.
+Returned Rect does not specify clipping Rect for Picture; cull is hint
+of Picture bounds.
+
+Picture is free to discard recorded drawing commands that fall outside 
+cull.
 
 #Return bounds passed when Picture was created ##
 
@@ -286,7 +303,7 @@ bounds may be drawn, and are drawn in this example.
 #In Property
 #Line # returns identifier for Picture ##
 
-Returns a non-zero value unique among all pictures.
+Returns a non-zero value unique among Pictures in Skia process.
 
 #Return identifier for Picture ##
 
@@ -312,7 +329,8 @@ placeholder id = 2
 #Method sk_sp<SkData> serialize(const SkSerialProcs* procs = nullptr) const
 #In Utility
 #Line # writes Picture to data ##
-Returns storage containing data describing Picture, using optional custom encoders.
+Returns storage containing data describing Picture, using optional custom
+encoders.
 
 #Param procs  custom serial data encoders; may be nullptr ##
 
@@ -368,9 +386,12 @@ Writes picture to stream, using optional custom encoders.
 #In Constructor
 #Line # constructs placeholder with unique identifier ##
 
-Returns a placeholder SkPicture.
-This placeholder does not draw anything itself.  It has a distinct uniqueID()
-(just like all Pictures) and will always be visible to SkSerialProcs.
+Returns a placeholder SkPicture. Result does not draw, and contains only
+cull Rect, a hint of its bounds. Result is immutable; it cannot be changed
+later. Result identifier is unique.
+
+Returned placeholder can be intercepted during playback to insert other
+commands into Canvas draw stream.
 
 #Param cull  placeholder dimensions
 ##
@@ -378,20 +399,31 @@ This placeholder does not draw anything itself.  It has a distinct uniqueID()
 #Return placeholder with unique identifier ##
 
 #Example
-sk_sp<SkPicture> pict1 = SkPicture::MakePlaceholder({10, 40, 80, 110});

-sk_sp<SkPicture> pict2 = SkPicture::MakePlaceholder({10, 40, 80, 110});

-for (auto pict : { pict1, pict2 } ) {

-    SkRect bounds = pict->cullRect();

-    SkDebugf("id:%d bounds:{%g, %g, %g, %g}\n", pict->uniqueID(), 

-             bounds.fLeft, bounds.fTop, bounds.fRight, bounds.fBottom);

-}
-#StdOut
-id:1 bounds:{10, 40, 80, 110}

-id:2 bounds:{10, 40, 80, 110}
+#Function
+class MyCanvas : public SkCanvas {
+public:
+    MyCanvas(SkCanvas* c) : canvas(c) {}
+        void onDrawPicture(const SkPicture* picture, const SkMatrix* ,

+                               const SkPaint* ) override {

+        const SkRect rect = picture->cullRect();
+        SkPaint redPaint;
+        redPaint.setColor(SK_ColorRED);
+        canvas->drawRect(rect, redPaint);
+   }
+
+   SkCanvas* canvas;

+};
 ##
+SkPictureRecorder recorder;

+SkCanvas* pictureCanvas = recorder.beginRecording({0, 0, 256, 256});

+sk_sp<SkPicture> placeholder = SkPicture::MakePlaceholder({10, 40, 80, 110});

+pictureCanvas->drawPicture(placeholder);

+sk_sp<SkPicture> picture = recorder.finishRecordingAsPicture();

+MyCanvas myCanvas(canvas);

+myCanvas.drawPicture(picture);

 ##
 
-#SeeAlso MakeFromStream MakeFromData
+#SeeAlso MakeFromStream MakeFromData uniqueID
 
 #Method ##
 
@@ -401,9 +433,9 @@ id:2 bounds:{10, 40, 80, 110}
 #In Property
 #Line # returns approximate operation count ##
 
-Returns the approximate number of operations in this picture.  This
-number may be greater or less than the number of SkCanvas calls
-recorded: some calls may be recorded as more than one operation, or some
+Returns the approximate number of operations in Picture. Returned value
+may be greater or less than the number of SkCanvas calls
+recorded: some calls may be recorded as more than one operation, other
 calls may be optimized away.
 
 #Return approximate operation count ##
@@ -432,7 +464,7 @@ calls may be optimized away.
 #Line # returns approximate size ##
 
 Returns the approximate byte size of Picture. Does not include large objects
-referenced Picture.
+referenced by Picture.
 
 #Return approximate size ##
 
diff --git a/docs/SkRRect_Reference.bmh b/docs/SkRRect_Reference.bmh
index 4b1a403e14..633239adde 100644
--- a/docs/SkRRect_Reference.bmh
+++ b/docs/SkRRect_Reference.bmh
@@ -5,15 +5,15 @@
 #Class SkRRect
 
 SkRRect describes a rounded rectangle with a bounds and a pair of radii for each corner.
-The bounds and radii can be set so that SkRRect describes a rectangle with sharp corners,
-a Circle, an Oval, or a rectangle with one or more rounded corners.
+The bounds and radii can be set so that SkRRect describes: a rectangle with sharp corners;
+a Circle; an Oval; or a rectangle with one or more rounded corners.
 
 SkRRect allows implementing CSS properties that describe rounded corners.
 SkRRect may have up to eight different radii, one for each axis on each of its four
 corners.
 
 SkRRect may modify the provided parameters when initializing bounds and radii.
-If either axis radii is zero or less, radii are stored as zero; corner is square.
+If either axis radii is zero or less: radii are stored as zero; corner is square.
 If corner curves overlap, radii are proportionally reduced to fit within bounds.
 
 #Subtopic Overview
@@ -170,7 +170,7 @@ less than half the height, or both.
 #Line # non-zero width and height with axis-aligned radii ##
 Round_Rect has width and height. Left x-radii are equal, top
 y-radii are equal, right x-radii are equal, and bottom y-radii
-are equal. The radii do not describe a rect, oval, or simple type.
+are equal. The radii do not describe Rect, Oval, or simple type.
 
 The centers of the corner ellipses form an axis-aligned rectangle
 that divides the Round_Rect into nine rectangular patches; an
diff --git a/site/user/api/SkCanvas_Reference.md b/site/user/api/SkCanvas_Reference.md
index d7da6132c7..75bf7645f8 100644
--- a/site/user/api/SkCanvas_Reference.md
+++ b/site/user/api/SkCanvas_Reference.md
@@ -4749,7 +4749,7 @@ error at the image edges.
 
 ### Example
 
-<div><fiddle-embed name="3b7b1f884437ab450f986234e4aec27f"><div>redBorder contains a black and white checkerboard bordered by red.
+<div><fiddle-embed name="5df49d1f4da37275a1f10ef7f1a749f0"><div>redBorder contains a black and white checkerboard bordered by red.
 redBorder is drawn scaled by 16 on the left.
 The middle and right bitmaps are filtered checkerboards.
 Drawing the checkerboard with <a href='#SkCanvas_kStrict_SrcRectConstraint'>kStrict SrcRectConstraint</a> shows only a blur of black and white.
diff --git a/site/user/api/SkImageInfo_Reference.md b/site/user/api/SkImageInfo_Reference.md
index 0156143d67..e1642271be 100644
--- a/site/user/api/SkImageInfo_Reference.md
+++ b/site/user/api/SkImageInfo_Reference.md
@@ -690,7 +690,7 @@ draw all colors possible to a <a href='#kRGB_101010x_SkColorType'>kRGB_101010x_S
 
 ### Example
 
-<div><fiddle-embed name="d8439ba8d23a424fa032fb97147fd2d2"></fiddle-embed></div>
+<div><fiddle-embed name="92f81aa0459230459600a01e79ccff29"></fiddle-embed></div>
 
 ### See Also
 
@@ -1469,7 +1469,7 @@ created <a href='#Image_Info'>Image Info</a>
 
 ### Example
 
-<div><fiddle-embed name="a2b1e0910f37066f15ae56368775a6d8"><div>Top gradient is drawn to offScreen without <a href='undocumented#Color_Space'>Color Space</a>. It is darker than middle
+<div><fiddle-embed name="de418ccb42471d1589508ef3955f8c53"><div>Top gradient is drawn to offScreen without <a href='undocumented#Color_Space'>Color Space</a>. It is darker than middle
 gradient, drawn to offScreen with sRGB <a href='undocumented#Color_Space'>Color Space</a>. Bottom gradient shares bits
 with middle, but does not specify the <a href='undocumented#Color_Space'>Color Space</a> in noColorSpaceBitmap. A source
 without <a href='undocumented#Color_Space'>Color Space</a> is treated as sRGB; the bottom gradient is identical to the
@@ -1870,7 +1870,7 @@ Returns <a href='undocumented#Color_Space'>Color Space</a>, the range of colors.
 
 ### Example
 
-<div><fiddle-embed name="6fb11419e99297fe2fe666c296117fb9"><div><a href='undocumented#SkColorSpace_MakeSRGBLinear'>SkColorSpace::MakeSRGBLinear</a> creates <a href='undocumented#Color_Space'>Color Space</a> with linear gamma
+<div><fiddle-embed name="5602b816d7cf75e3851274ef36a4c10f"><div><a href='undocumented#SkColorSpace_MakeSRGBLinear'>SkColorSpace::MakeSRGBLinear</a> creates <a href='undocumented#Color_Space'>Color Space</a> with linear gamma
 and an sRGB gamut. This <a href='undocumented#Color_Space'>Color Space</a> gamma is not close to sRGB gamma.
 </div>
 
diff --git a/site/user/api/SkImage_Reference.md b/site/user/api/SkImage_Reference.md
index 16fa9fb6f8..ad21311548 100644
--- a/site/user/api/SkImage_Reference.md
+++ b/site/user/api/SkImage_Reference.md
@@ -1053,7 +1053,7 @@ created <a href='#Image'>Image</a>, or nullptr
 
 ### Example
 
-<div><fiddle-embed name="67b6609471a3f1ed0f4b1657004cdecb" gpu="true"></fiddle-embed></div>
+<div><fiddle-embed name="b034517e39394b7543f06ec885e36d7d" gpu="true"></fiddle-embed></div>
 
 ### See Also
 
@@ -2300,7 +2300,7 @@ partial or full <a href='#Image'>Image</a>, or nullptr
 
 ### Example
 
-<div><fiddle-embed name="fef2a36bee224e92500199fa9d3cbb8b"></fiddle-embed></div>
+<div><fiddle-embed name="93669037c9eb9d142e7776b9f936fa96"></fiddle-embed></div>
 
 ### See Also
 
diff --git a/site/user/api/SkMatrix_Reference.md b/site/user/api/SkMatrix_Reference.md
index 5f5aa11e77..b780eb27e1 100644
--- a/site/user/api/SkMatrix_Reference.md
+++ b/site/user/api/SkMatrix_Reference.md
@@ -4920,7 +4920,7 @@ true if <a href='#SkMatrix_mapRect_dst'>dst</a> is equivalent to mapped <a href=
 
 ### Example
 
-<div><fiddle-embed name="67b6609471a3f1ed0f4b1657004cdecb"></fiddle-embed></div>
+<div><fiddle-embed name="dbcf928b035a31ca69c99392e2e2cca9"></fiddle-embed></div>
 
 ### See Also
 
diff --git a/site/user/api/SkPaint_Reference.md b/site/user/api/SkPaint_Reference.md
index 3acb9303d6..342579d231 100644
--- a/site/user/api/SkPaint_Reference.md
+++ b/site/user/api/SkPaint_Reference.md
@@ -4037,7 +4037,7 @@ Does not alter <a href='undocumented#Typeface'>Typeface</a> <a href='undocumente
 
 ### Example
 
-<div><fiddle-embed name="d307e7e1237f39fb54d80723e5449857">
+<div><fiddle-embed name="5ce718e5a184baaac80e7098d7dad67b">
 
 #### Example Output
 
@@ -5401,7 +5401,7 @@ number of <a href='undocumented#Glyph'>Glyphs</a> represented by <a href='#SkPai
 
 ### Example
 
-<div><fiddle-embed name="6fb11419e99297fe2fe666c296117fb9">
+<div><fiddle-embed name="85436c71aab5410767fc688ab0573e09">
 
 #### Example Output
 
@@ -5682,7 +5682,7 @@ glyph count in <a href='#SkPaint_getTextWidths_text'>text</a>
 
 ### Example
 
-<div><fiddle-embed name="6fb11419e99297fe2fe666c296117fb9"><div>Bounds of <a href='undocumented#Glyph'>Glyphs</a> increase for stroked <a href='#SkPaint_getTextWidths_text'>text</a>, but <a href='#SkPaint_getTextWidths_text'>text</a> advance remains the same.
+<div><fiddle-embed name="6b9e101f49e9c2c28755c5bdcef64dfb"><div>Bounds of <a href='undocumented#Glyph'>Glyphs</a> increase for stroked <a href='#SkPaint_getTextWidths_text'>text</a>, but <a href='#SkPaint_getTextWidths_text'>text</a> advance remains the same.
 The underlines show the <a href='#SkPaint_getTextWidths_text'>text</a> advance, spaced to keep them distinct.
 </div></fiddle-embed></div>
 
diff --git a/site/user/api/SkPath_Reference.md b/site/user/api/SkPath_Reference.md
index e03e5c3c3c..9442e4d14a 100644
--- a/site/user/api/SkPath_Reference.md
+++ b/site/user/api/SkPath_Reference.md
@@ -3698,7 +3698,7 @@ The length of <a href='SkPoint_Reference#Vector'>Vector</a> from (<a href='#SkPa
 
 ### Example
 
-<div><fiddle-embed name="d8439ba8d23a424fa032fb97147fd2d2"></fiddle-embed></div>
+<div><fiddle-embed name="01d2ddfd539ab86a86989e210640dffc"></fiddle-embed></div>
 
 <a href='#Arc'>Arc</a> sweep is always less than 180 degrees. If <a href='#SkPath_arcTo_2_radius'>radius</a> is zero, or if
 tangents are nearly parallel, <a href='#SkPath_arcTo'>arcTo</a> appends <a href='undocumented#Line'>Line</a> from last <a href='#Path'>Path</a> <a href='SkPoint_Reference#Point'>Point</a> to (<a href='#SkPath_arcTo_2_x1'>x1</a>, <a href='#SkPath_arcTo_2_y1'>y1</a>).
@@ -5454,7 +5454,7 @@ from output.
 
 ### Example
 
-<div><fiddle-embed name="67b6609471a3f1ed0f4b1657004cdecb">
+<div><fiddle-embed name="92e0032f85181795d1f8b5a2c8e4e4b7">
 
 #### Example Output
 
@@ -6035,7 +6035,7 @@ true if last <a href='#SkPath_kLine_Verb'>kLine Verb</a> was generated by <a hre
 
 ### Example
 
-<div><fiddle-embed name="67b6609471a3f1ed0f4b1657004cdecb">
+<div><fiddle-embed name="7000b501f49341629bfdd9f80e686103">
 
 #### Example Output
 
diff --git a/site/user/api/SkPicture_Reference.md b/site/user/api/SkPicture_Reference.md
index 0992737b04..1d8c1bbc84 100644
--- a/site/user/api/SkPicture_Reference.md
+++ b/site/user/api/SkPicture_Reference.md
@@ -26,8 +26,16 @@ SkPicture can be constructed or initialized by these functions, including C++ cl
   </tr>
 </table>
 
-An <a href='#SkPicture'>SkPicture</a> records drawing commands made to a canvas to be played back at a later time.
-This base class handles serialization and a few other miscellany.
+<a href='#Picture'>Picture</a> records drawing commands made to <a href='SkCanvas_Reference#Canvas'>Canvas</a>. The command stream may be
+played in whole or in part at a later time.
+
+<a href='#Picture'>Picture</a> is an abstract class. <a href='#Picture'>Picture</a> may be generated by <a href='undocumented#Picture_Recorder'>Picture Recorder</a>
+or <a href='undocumented#Drawable'>Drawable</a>, or from <a href='#Picture'>Picture</a> previously saved to <a href='undocumented#Data'>Data</a> or <a href='undocumented#Stream'>Stream</a>.
+
+<a href='#Picture'>Picture</a> may contain any <a href='SkCanvas_Reference#Canvas'>Canvas</a> drawing command, as well as one or more
+<a href='SkCanvas_Reference#Matrix'>Canvas Matrix</a> or <a href='SkCanvas_Reference#Clip'>Canvas Clip</a>. <a href='#Picture'>Picture</a> has a cull <a href='SkRect_Reference#Rect'>Rect</a>, which is used as
+a bounding box hint. To limit <a href='#Picture'>Picture</a> bounds, use <a href='SkCanvas_Reference#Clip'>Canvas Clip</a> when
+recording or drawing <a href='#Picture'>Picture</a>.
 
 ## Overview
 
@@ -134,13 +142,11 @@ SkPicture member functions read and modify the structure properties.
         virtual
 </pre>
 
-<a href='undocumented#Subclasses'>Subclasses</a> of this can be passed to <a href='#SkPicture_playback'>playback</a>. During the playback
-of the picture, this callback will periodically be invoked. If its
-<a href='#SkPicture_AbortCallback_abort'>abort</a> returns true, then picture playback will be interrupted.
-The resulting drawing is undefined, as there is no guarantee how often the
-callback will be invoked. If the abort happens inside some level of nested
-calls to save(), restore will automatically be called to return the state
-to the same level it was before the playback call was made.
+<a href='#SkPicture_AbortCallback_empty_constructor'>AbortCallback</a> is an abstract class. An implementation of <a href='#SkPicture_AbortCallback_empty_constructor'>AbortCallback</a> may
+passed as a parameter to <a href='#SkPicture_playback'>SkPicture::playback</a>, to stop it before all drawing
+commands have been processed.
+
+If <a href='#SkPicture_AbortCallback_abort'>AbortCallback::abort</a> returns true, <a href='#SkPicture_playback'>SkPicture::playback</a> is interrupted.
 
 <a name='SkPicture_AbortCallback_empty_constructor'></a>
 ## AbortCallback
@@ -184,8 +190,14 @@ virtual bool <a href='#SkPicture_AbortCallback_abort'>abort</a>() = 0
 </pre>
 
 Stops <a href='#Picture'>Picture</a> playback when some condition is met. A subclass of
-<a href='#SkPicture_AbortCallback_empty_constructor'>AbortCallback</a> provides an override for <a href='#SkPicture_AbortCallback_abort'>abort</a> that can stop <a href='#SkPicture_playback'>playback</a> from
-drawing the entire picture.
+<a href='#SkPicture_AbortCallback_empty_constructor'>AbortCallback</a> provides an override for <a href='#SkPicture_AbortCallback_abort'>abort</a> that can stop <a href='#SkPicture_playback'>SkPicture::playback</a>.
+
+The part of <a href='#Picture'>Picture</a> drawn when aborted is undefined. <a href='#Picture'>Picture</a> instantiations are
+free to stop drawing at different points during playback.
+
+If the abort happens inside one or more calls to <a href='SkCanvas_Reference#SkCanvas_save'>SkCanvas::save()</a>, stack
+of <a href='SkCanvas_Reference#Matrix'>Canvas Matrix</a> and <a href='SkCanvas_Reference#Clip'>Canvas Clip</a> values is restored to its state before
+<a href='#SkPicture_playback'>SkPicture::playback</a> was called.
 
 ### Return Value
 
@@ -312,10 +324,11 @@ Recreates a picture that was serialized into <a href='#SkPicture_MakeFromData_2_
 virtual void <a href='#SkPicture_playback'>playback</a>(<a href='SkCanvas_Reference#SkCanvas'>SkCanvas</a>* canvas, <a href='#SkPicture_AbortCallback'>AbortCallback</a>* callback = nullptr) const = 0
 </pre>
 
-Replays the drawing commands on the specified <a href='#SkPicture_playback_canvas'>canvas</a>. Note that
-this has the effect of unfurling this picture into the destination
-<a href='#SkPicture_playback_canvas'>canvas</a>. Using the <a href='SkCanvas_Reference#SkCanvas_drawPicture'>SkCanvas::drawPicture</a> entry point gives the destination
-<a href='#SkPicture_playback_canvas'>canvas</a> the option of just taking a ref.
+Replays the drawing commands on the specified <a href='#SkPicture_playback_canvas'>canvas</a>. In the case that the
+commands are recorded, each command in the <a href='#Picture'>Picture</a> is sent separately to <a href='#SkPicture_playback_canvas'>canvas</a>.
+
+To add a single command to draw <a href='#Picture'>Picture</a> to recording <a href='#SkPicture_playback_canvas'>canvas</a>, call
+<a href='SkCanvas_Reference#SkCanvas_drawPicture'>SkCanvas::drawPicture</a> instead.
 
 ### Parameters
 
@@ -344,8 +357,12 @@ this has the effect of unfurling this picture into the destination
 virtual <a href='SkRect_Reference#SkRect'>SkRect</a> <a href='#SkPicture_cullRect'>cullRect</a>() const = 0
 </pre>
 
-Returns cull <a href='SkRect_Reference#Rect'>Rect</a> for this picture.
-Ops recorded into this picture that attempt to draw outside the cull might not be drawn.
+Returns cull <a href='SkRect_Reference#Rect'>Rect</a> for this picture, passed in when <a href='#Picture'>Picture</a> was created.
+Returned <a href='SkRect_Reference#Rect'>Rect</a> does not specify clipping <a href='SkRect_Reference#Rect'>Rect</a> for <a href='#Picture'>Picture</a>; cull is hint
+of <a href='#Picture'>Picture</a> bounds.
+
+<a href='#Picture'>Picture</a> is free to discard recorded drawing commands that fall outside
+cull.
 
 ### Return Value
 
@@ -370,7 +387,7 @@ bounds may be drawn, and are drawn in this example.
 uint32_t <a href='#SkPicture_uniqueID'>uniqueID</a>() const
 </pre>
 
-Returns a non-zero value unique among all pictures.
+Returns a non-zero value unique among <a href='#Picture'>Pictures</a> in Skia process.
 
 ### Return Value
 
@@ -402,7 +419,8 @@ placeholder id = 2
 <a href='undocumented#sk_sp'>sk sp</a>&lt;<a href='undocumented#SkData'>SkData</a>&gt; <a href='#SkPicture_serialize'>serialize</a>(const <a href='undocumented#SkSerialProcs'>SkSerialProcs</a>* procs = nullptr) const
 </pre>
 
-Returns storage containing data describing <a href='#Picture'>Picture</a>, using optional custom encoders.
+Returns storage containing data describing <a href='#Picture'>Picture</a>, using optional custom
+encoders.
 
 ### Parameters
 
@@ -460,9 +478,12 @@ Writes picture to <a href='#SkPicture_serialize_2_stream'>stream</a>, using opti
 static <a href='undocumented#sk_sp'>sk sp</a>&lt;<a href='#SkPicture'>SkPicture</a>&gt; <a href='#SkPicture_MakePlaceholder'>MakePlaceholder</a>(<a href='SkRect_Reference#SkRect'>SkRect</a> cull)
 </pre>
 
-Returns a placeholder <a href='#SkPicture'>SkPicture</a>.
-This placeholder does not draw anything itself.  It has a distinct <a href='#SkPicture_uniqueID'>uniqueID</a>
-(just like all <a href='#Picture'>Pictures</a>) and will always be visible to <a href='undocumented#SkSerialProcs'>SkSerialProcs</a>.
+Returns a placeholder <a href='#SkPicture'>SkPicture</a>. Result does not draw, and contains only
+<a href='#SkPicture_MakePlaceholder_cull'>cull</a> <a href='SkRect_Reference#Rect'>Rect</a>, a hint of its bounds. Result is immutable; it cannot be changed
+later. Result identifier is unique.
+
+Returned placeholder can be intercepted during playback to insert other
+commands into <a href='SkCanvas_Reference#Canvas'>Canvas</a> draw stream.
 
 ### Parameters
 
@@ -477,20 +498,11 @@ placeholder with unique identifier
 
 ### Example
 
-<div><fiddle-embed name="32f84819483a906ede9c5525801845ef">
-
-#### Example Output
-
-~~~~
-id:1 bounds:{10, 40, 80, 110}
-id:2 bounds:{10, 40, 80, 110}
-~~~~
-
-</fiddle-embed></div>
+<div><fiddle-embed name="0d2cbf82f490ffb180e0b4531afa232c"></fiddle-embed></div>
 
 ### See Also
 
-<a href='#SkPicture_MakeFromStream'>MakeFromStream</a> <a href='#SkPicture_MakeFromData'>MakeFromData</a><sup><a href='#SkPicture_MakeFromData_2'>[2]</a></sup>
+<a href='#SkPicture_MakeFromStream'>MakeFromStream</a> <a href='#SkPicture_MakeFromData'>MakeFromData</a><sup><a href='#SkPicture_MakeFromData_2'>[2]</a></sup> <a href='#SkPicture_uniqueID'>uniqueID</a>
 
 ---
 
@@ -501,9 +513,9 @@ id:2 bounds:{10, 40, 80, 110}
 virtual int <a href='#SkPicture_approximateOpCount'>approximateOpCount</a>() const = 0
 </pre>
 
-Returns the approximate number of operations in this picture.  This
-number may be greater or less than the number of <a href='SkCanvas_Reference#SkCanvas'>SkCanvas</a> calls
-recorded: some calls may be recorded as more than one operation, or some
+Returns the approximate number of operations in <a href='#Picture'>Picture</a>. Returned value
+may be greater or less than the number of <a href='SkCanvas_Reference#SkCanvas'>SkCanvas</a> calls
+recorded: some calls may be recorded as more than one operation, other
 calls may be optimized away.
 
 ### Return Value
@@ -528,7 +540,7 @@ virtual size_t <a href='#SkPicture_approximateBytesUsed'>approximateBytesUsed</a
 </pre>
 
 Returns the approximate byte size of <a href='#Picture'>Picture</a>. Does not include large objects
-referenced <a href='#Picture'>Picture</a>.
+referenced by <a href='#Picture'>Picture</a>.
 
 ### Return Value
 
diff --git a/site/user/api/SkRRect_Reference.md b/site/user/api/SkRRect_Reference.md
index e83c3cfe6b..aa43f16ae5 100644
--- a/site/user/api/SkRRect_Reference.md
+++ b/site/user/api/SkRRect_Reference.md
@@ -84,15 +84,15 @@ SkRRect global, <code>struct</code>, and <code>class</code> related member funct
 </table>
 
 <a href='#SkRRect'>SkRRect</a> describes a rounded rectangle with a bounds and a pair of radii for each corner.
-The bounds and radii can be set so that <a href='#SkRRect'>SkRRect</a> describes a rectangle with sharp corners,
-a <a href='undocumented#Circle'>Circle</a>, an <a href='undocumented#Oval'>Oval</a>, or a rectangle with one or more rounded corners.
+The bounds and radii can be set so that <a href='#SkRRect'>SkRRect</a> describes: a rectangle with sharp corners;
+a <a href='undocumented#Circle'>Circle</a>; an <a href='undocumented#Oval'>Oval</a>; or a rectangle with one or more rounded corners.
 
 <a href='#SkRRect'>SkRRect</a> allows implementing CSS properties that describe rounded corners.
 <a href='#SkRRect'>SkRRect</a> may have up to eight different radii, one for each axis on each of its four
 corners.
 
 <a href='#SkRRect'>SkRRect</a> may modify the provided parameters when initializing bounds and radii.
-If either axis radii is zero or less, radii are stored as zero; corner is square.
+If either axis radii is zero or less: radii are stored as zero; corner is square.
 If corner curves overlap, radii are proportionally reduced to fit within bounds.
 
 ## Overview
@@ -481,7 +481,7 @@ less than half the height, or both.
     <td style='text-align: left; border: 2px solid #dddddd; padding: 8px; '>
 <a href='#RRect'>Round Rect</a> has width and height. Left x-radii are equal, top
 y-radii are equal, right x-radii are equal, and bottom y-radii
-are equal. The radii do not describe a rect, oval, or simple type.
+are equal. The radii do not describe <a href='SkRect_Reference#Rect'>Rect</a>, <a href='undocumented#Oval'>Oval</a>, or simple type.
 
 The centers of the corner ellipses form an axis-aligned rectangle
 that divides the <a href='#RRect'>Round Rect</a> into nine rectangular patches; an
diff --git a/site/user/api/SkRect_Reference.md b/site/user/api/SkRect_Reference.md
index 08364fcb84..e0402bf2f6 100644
--- a/site/user/api/SkRect_Reference.md
+++ b/site/user/api/SkRect_Reference.md
@@ -2985,7 +2985,7 @@ Has no effect if <a href='#SkRect_join_2_r'>r</a> is empty. Otherwise, if <a hre
 
 ### Example
 
-<div><fiddle-embed name="3b7b1f884437ab450f986234e4aec27f">
+<div><fiddle-embed name="26500032494cf93c5fa3423110fe82af">
 
 #### Example Output
 
diff --git a/site/user/api/catalog.htm b/site/user/api/catalog.htm
index 7ad0dc349d..aede7441de 100644
--- a/site/user/api/catalog.htm
+++ b/site/user/api/catalog.htm
@@ -2373,13 +2373,6 @@
     "name": "SkPath::writeToMemory",
         "stdout": "path is equal to copy\\n"
     },
-        "SkPicture_MakePlaceholder": {
-    "code": "void draw(SkCanvas* canvas) {\n    sk_sp<SkPicture> pict1 = SkPicture::MakePlaceholder({10, 40, 80, 110});\n    sk_sp<SkPicture> pict2 = SkPicture::MakePlaceholder({10, 40, 80, 110});\n    for (auto pict : { pict1, pict2 } ) {\n        SkRect bounds = pict->cullRect();\n        SkDebugf(\"id:%d bounds:{%g, %g, %g, %g}\\n\", pict->uniqueID(), \n                 bounds.fLeft, bounds.fTop, bounds.fRight, bounds.fBottom);\n    }\n}",
-    "hash": "32f84819483a906ede9c5525801845ef",
-    "file": "SkPicture_Reference",
-    "name": "SkPicture::MakePlaceholder",
-        "stdout": "id:1 bounds:{10, 40, 80, 110}\\nid:2 bounds:{10, 40, 80, 110}\\n"
-    },
         "SkPicture_uniqueID": {
     "code": "void draw(SkCanvas* canvas) {\n    SkPictureRecorder recorder;\n    recorder.beginRecording({0, 0, 0, 0});\n    sk_sp<SkPicture> picture = recorder.finishRecordingAsPicture();\n    SkDebugf(\"empty picture id = %d\\n\", picture->uniqueID());\n    sk_sp<SkPicture> placeholder = SkPicture::MakePlaceholder({0, 0, 0, 0});\n    SkDebugf(\"placeholder id = %d\\n\", placeholder->uniqueID());\n}",
     "hash": "8e4257245c988c600410fe4fd7293f07",
@@ -7199,6 +7192,14 @@
     "file": "SkPicture_Reference",
     "name": "SkPicture::MakeFromStream"
 },
+    "SkPicture_MakePlaceholder": {
+    "code": "class MyCanvas : public SkCanvas {\npublic:\n    MyCanvas(SkCanvas* c) : canvas(c) {}\n        void onDrawPicture(const SkPicture* picture, const SkMatrix* ,\n                               const SkPaint* ) override {\n        const SkRect rect = picture->cullRect();\n        SkPaint redPaint;\n        redPaint.setColor(SK_ColorRED);\n        canvas->drawRect(rect, redPaint);\n   }\n   SkCanvas* canvas;\n};\n\nvoid draw(SkCanvas* canvas) {\n    SkPictureRecorder recorder;\n    SkCanvas* pictureCanvas = recorder.beginRecording({0, 0, 256, 256});\n    sk_sp<SkPicture> placeholder = SkPicture::MakePlaceholder({10, 40, 80, 110});\n    pictureCanvas->drawPicture(placeholder);\n    sk_sp<SkPicture> picture = recorder.finishRecordingAsPicture();\n    MyCanvas myCanvas(canvas);\n    myCanvas.drawPicture(picture);\n}",
+    "width": 256,
+    "height": 256,
+    "hash": "0d2cbf82f490ffb180e0b4531afa232c",
+    "file": "SkPicture_Reference",
+    "name": "SkPicture::MakePlaceholder"
+},
     "SkPicture_approximateBytesUsed": {
     "code": "void draw(SkCanvas* canvas) {\n    SkPictureRecorder recorder;\n    SkCanvas* pictureCanvas = recorder.beginRecording({0, 0, 256, 256});\n    SkPaint paint;\n    pictureCanvas->drawRect(SkRect::MakeWH(200, 200), paint);\n    paint.setColor(SK_ColorWHITE);\n    pictureCanvas->drawRect(SkRect::MakeLTRB(20, 20, 180, 180), paint);\n    sk_sp<SkPicture> picture = recorder.finishRecordingAsPicture();\n    picture->playback(canvas);\n    std::string opCount = \"approximate bytes used: \" + std::to_string(picture->approximateBytesUsed());\n    canvas->drawString(opCount.c_str(), 20, 220, SkPaint());\n}",
     "width": 256,
diff --git a/tools/bookmaker/bookmaker.cpp b/tools/bookmaker/bookmaker.cpp
index 65f89f5dfe..ffd3012e24 100644
--- a/tools/bookmaker/bookmaker.cpp
+++ b/tools/bookmaker/bookmaker.cpp
@@ -83,6 +83,9 @@ has #Const children. If so, generate a summary table first.
 Or, only allow #Line and moderate text description in #Const. Put more verbose text, example,
 seealso, in subsequent #SubTopic. Alpha_Type does this and it looks good.
 
+picture reference subclass AbortCallback has empty subtopics, and fails to show the full
+prototype for ~AbortCallback in the md out generation.
+
 see head of selfCheck.cpp for additional todos
 see head of spellCheck.cpp for additional todos
  */