fix param return descriptions

enforce that param and return
descriptions are phrases (begin
with lower case, no trailing
period).

Docs-Preview: https://skia.org/?cl=40767
Bug: skia: 6898
Change-Id: Ib5f2a02441673f71c0780d81c5e4c61200a678e3
Reviewed-on: https://skia-review.googlesource.com/40767
Commit-Queue: Cary Clark <caryclark@skia.org>
Reviewed-by: Cary Clark <caryclark@skia.org>

12 files changed, 189 insertions, 103 deletions

diff --git a/docs/SkCanvas_Reference.bmh b/docs/SkCanvas_Reference.bmh
index 0168afae77..8a4fe87fd0 100644
--- a/docs/SkCanvas_Reference.bmh
+++ b/docs/SkCanvas_Reference.bmh
@@ -818,7 +818,7 @@ If pixels are inaccessible, info, rowBytes, and origin are unchanged.
                  may be nullptr
 ##
 
-#Return  Address of pixels, or nullptr if inaccessible ##
+#Return  address of pixels, or nullptr if inaccessible ##
 
 #Example
 void draw(SkCanvas* canvas) {
@@ -2366,7 +2366,7 @@ Replace Clip with the intersection or difference of Clip and rect,
 with an aliased or anti-aliased clip edge. rect is transformed by Matrix
 before it is combined with Clip.
 
-#Param  rect  Rectangle to combine with Clip ##
+#Param  rect  Rect to combine with Clip ##
 #Param  op    Clip_Op to apply to Clip ##
 #Param  doAntiAlias  true if Clip is to be anti-aliased ##
 
@@ -2396,7 +2396,7 @@ Replace Clip with the intersection or difference of Clip and rect.
 Resulting Clip is aliased; pixels are fully contained by the clip.
 rect is transformed by Matrix before it is combined with Clip.
 
-#Param  rect  Rectangle to combine with Clip ##
+#Param  rect  Rect to combine with Clip ##
 #Param  op    Clip_Op to apply to Clip ##
 
 #Example
@@ -2425,7 +2425,7 @@ Resulting Clip is aliased; pixels are fully contained by the clip.
 rect is transformed by Matrix
 before it is combined with Clip.
 
-#Param  rect  Rectangle to combine with Clip ##
+#Param  rect   Rect to combine with Clip ##
 #Param  doAntiAlias  true if Clip is to be anti-aliased ##
 
 #Example
@@ -3140,10 +3140,10 @@ Always draws each element one at a time; is not affected by
 Paint_Stroke_Join, and unlike drawPath, does not create a mask from all points
 and lines before drawing. 
 
-#Param  mode     Whether pts draws points or lines ##
-#Param  count    The number of points in the array ##
-#Param  pts      Array of points to draw ##
-#Param  paint    Stroke, blend, color, and so on, used to draw ##
+#Param  mode     whether pts draws points or lines ##
+#Param  count    number of points in the array ##
+#Param  pts      array of points to draw ##
+#Param  paint    stroke, blend, color, and so on, used to draw ##
 
 #Example
 #Height 200
@@ -4496,7 +4496,7 @@ improve performance.
 #Param  paint    Paint containing Blend_Mode, Color_Filter, Image_Filter,
                  and so on; or nullptr
 ##
-#Param  constraint Filter strictly within src or draw faster ##
+#Param  constraint sample strictly within src, or draw faster ##
 
 #Example
 #Height 64
@@ -5164,7 +5164,7 @@ filled 12 point black glyphs.
 #Param  byteLength   byte length of text array ##
 #Param  path         Path providing text baseline ##
 #Param  matrix       transform of glyphs before mapping to path; may be nullptr
-                     to use identity Matrix.
+                     to use identity Matrix
 ##
 #Param  paint        text size, blend, color, and so on, used to draw ##
 
@@ -5571,7 +5571,7 @@ bottom right, bottom left order.
 If paint contains Shader, Point array texCoords maps Shader as texture to
 corners in top left, top right, bottom right, bottom left order.
 
-#Param cubics     Cubic array, sharing common points ##
+#Param cubics     Path_Cubic array, sharing common points ##
 #Param colors     Color array, one for each corner ##
 #Param texCoords  Point array of texure coordinates, mapping Shader to corners;
                   may be nullptr 
@@ -5629,7 +5629,7 @@ bottom right, bottom left order.
 If paint contains Shader, Point array texCoords maps Shader as texture to
 corners in top left, top right, bottom right, bottom left order.
 
-#Param cubics     Cubic array, sharing common points ##
+#Param cubics     Path_Cubic array, sharing common points ##
 #Param colors     Color array, one for each corner ##
 #Param texCoords  Point array of texure coordinates, mapping Shader to corners;
                   may be nullptr 
diff --git a/docs/SkPaint_Reference.bmh b/docs/SkPaint_Reference.bmh
index cc9ae93fbe..e25a51c5f3 100644
--- a/docs/SkPaint_Reference.bmh
+++ b/docs/SkPaint_Reference.bmh
@@ -3647,7 +3647,7 @@ Deprecated.
     Pass nullptr to clear Draw_Looper and leave Draw_Looper effect on drawing unaltered.
     Does not alter drawLooper Reference_Count.
 
-    #Param drawLooper  Iterates through drawing one or more time, altering Paint ##
+    #Param drawLooper  iterates through drawing one or more time, altering Paint ##
 
     #Example
     #Height 128
@@ -4975,7 +4975,7 @@ void draw(SkCanvas* canvas) {
     #Param bounds        lower and upper line parallel to the advance ##
     #Param intervals     returned intersections; may be nullptr ##
 
-    #Return              The number of intersections; may be zero ##
+    #Return              number of intersections; may be zero ##
 
     #Example
     #Description
diff --git a/docs/SkPath_Reference.bmh b/docs/SkPath_Reference.bmh
index a0508dff29..e4b9770543 100644
--- a/docs/SkPath_Reference.bmh
+++ b/docs/SkPath_Reference.bmh
@@ -532,7 +532,7 @@ pointers are not exposed.
 
 #Param path  Path to copy by value ##
 
-#Return  Copy of Path ##
+#Return  copy of Path ##
 
 #Example
 #Description
@@ -1079,7 +1079,7 @@ Computes Convexity if required, and returns stored value.
 Convexity is computed if stored value is kUnknown_Convexity,
 or if Path has been altered since Convexity was computed or set.
 
-#Return  Computed or stored Convexity ##
+#Return  computed or stored Convexity ##
 
 #Example
 void draw(SkCanvas* canvas) {
@@ -1109,7 +1109,7 @@ void draw(SkCanvas* canvas) {
 Returns last computed Convexity, or kUnknown_Convexity if 
 Path has been altered since Convexity was computed or set.
 
-#Return  Stored Convexity ##
+#Return  stored Convexity ##
 
 #Example
 #Description
@@ -1571,11 +1571,12 @@ Test if Line between Point pair is degenerate.
 Line with no length or that moves a very short distance is degenerate; it is
 treated as a point. 
 
+exact changes the equality test. If true, returns true only if p1 equals p2.
+If false, returns true if p1 equals or nearly equals p2.
+
 #Param p1     line start point ##
 #Param p2     line end point ##
-#Param exact  If true, returns true only if p1 equals p2. If false, returns true
-              if p1 equals or nearly equals p2 
-##
+#Param exact  if false, allow nearly equals ##
 
 #Return  true if Line is degenerate; its length is effectively zero ##
 
@@ -3821,7 +3822,7 @@ of up to 90 degrees; in this case, set pow2 to one.
 #Param pts   storage for Quad array ##
 #Param pow2  Quad count, as power of two, normally 0 to 5 (1 to 32 Quad curves) ##
 
-#Return  Number of Quad curves written to pts ##
+#Return  number of Quad curves written to pts ##
 
 #Example
 #Description
@@ -4022,7 +4023,7 @@ start determines the first corner added.
 
 #Param rect   Rect to add as a closed contour ##
 #Param dir    Direction to wind added contour ##
-#Param start  Initial corner of Rect to add ##
+#Param start  initial corner of Rect to add ##
 
 #Example
 #Height 128
@@ -4434,7 +4435,7 @@ After appending, Path may be empty, or may contain: Rect, Oval, or Round_Rect.
 
 #Param rrect  bounds and radii of rounded rectangle ##
 #Param dir    Direction to wind Round_Rect ##
-#Param start  Index of initial point of Round_Rect ##
+#Param start  index of initial point of Round_Rect ##
 
 #Example
 void draw(SkCanvas* canvas) {
@@ -4472,8 +4473,8 @@ appends kClose_Verb to Path, connecting pts[count - 1] and pts[0].
 If count is zero, append kMove_Verb to path.
 Has no effect if count is less than one.
   
-#Param pts    Array of Line sharing end and start Point ##
-#Param count  Length of Point array ##
+#Param pts    array of Line sharing end and start Point ##
+#Param count  length of Point array ##
 #Param close  true to add Line connecting Contour end and start ##
 
 #Example
@@ -4635,7 +4636,7 @@ added unaltered. If mode is kExtend_AddPathMode, add Line before appending
 Verbs, Points, and Conic_Weights. 
 
 #Param src     Path Verbs, Points, and Conic_Weights to add ##
-#Param matrix  Transform applied to src ##
+#Param matrix  transform applied to src ##
 #Param mode    kAppend_AddPathMode or kExtend_AddPathMode ##
 
 #Example
@@ -5519,20 +5520,20 @@ kDone_Verb
 
 #Method Verb next(SkPoint pts[4], bool doConsumeDegenerates = true, bool exact = false) 
 
-        Returns next Verb in Verb_Array, and advances Iter.
-        When Verb_Array is exhausted, returns kDone_Verb.
+Returns next Verb in Verb_Array, and advances Iter.
+When Verb_Array is exhausted, returns kDone_Verb.
+
 Zero to four Points are stored in pts, depending on the returned Verb.
+
 If doConsumeDegenerates is true, skip consecutive kMove_Verb entries, returning
 only the last in the series; and skip very small Lines, Quads, and Conics; and
 skip kClose_Verb following kMove_Verb.
 if doConsumeDegenerates is true and exact is true, only skip Lines, Quads, and
 Conics with zero lengths.
 
-    #Param  pts Storage for Point data describing returned Verb ##
-    #Param doConsumeDegenerates If true, skip degenerate Verbs ##
-    #Param exact If true, skip zero length curves. Has no effect if doConsumeDegenerates
-                 is false 
-    ##
+    #Param  pts storage for Point data describing returned Verb ##
+    #Param doConsumeDegenerates if true, skip degenerate Verbs ##
+    #Param exact skip zero length curves ##
 
     #Return next Verb from Verb_Array  ##
 
@@ -5777,7 +5778,7 @@ Verb_Array, Point_Array, and Conic_Weight are returned unaltered.
         When Verb_Array is exhausted, returns kDone_Verb.
         Zero to four Points are stored in pts, depending on the returned Verb.
 
-        #Param  pts Storage for Point data describing returned Verb ##
+        #Param  pts storage for Point data describing returned Verb ##
 
         #Return next Verb from Verb_Array  ##
 
diff --git a/docs/undocumented.bmh b/docs/undocumented.bmh
index e3c0bedb1b..0be5a0f0c5 100644
--- a/docs/undocumented.bmh
+++ b/docs/undocumented.bmh
@@ -14,7 +14,7 @@
  NULL
  RFC
  Bezier Coons Cartesian
- C C++
+ C C++ 
  SaveLayerFlags # not external; need to add typedef support
  SkUserConfig.h  # not external, but still thinking about how markup refers to this
  SkXXX.h        # ditto
diff --git a/docs/usingBookmaker.bmh b/docs/usingBookmaker.bmh
index 5a088b3d02..60505ca279 100644
--- a/docs/usingBookmaker.bmh
+++ b/docs/usingBookmaker.bmh
@@ -2,7 +2,7 @@
 SkXXX

 bmh_SkXXX

 CL

-C

+Go

 Visual_Studio

 ##

 

@@ -10,7 +10,9 @@ Visual_Studio
 

 How to use the Bookmaker utility.

 

+Install #A Go # https://golang.org/doc/install ## if needed.  

 Get the fiddle command line interface tool.

+By default this will appear in your home directory.

 

 #Code

 $ go get go.skia.org/infra/fiddle/go/fiddlecli

@@ -33,6 +35,39 @@ $ ./out/dir/bookmaker -t -i include/core/SkXXX.h
 Copy SkXXX.bmh to docs.

 Use your favorite editor to fill out docs/SkXXX.bmh.

 

+#Subtopic Style

+

+Documentation consists of cross references, descriptions, and examples.

+All structs, classes, enums, their members and methods, functions, and so on,

+require descriptions. Most also require examples.

+

+All methods and functions should include examples if practical.

+

+Descriptions start with an active verb. Descriptions are complete, punctuated

+sentences unless they describe parameters or return values. Parameters and

+returned values are described by phrases that start lower case and do not

+include trailing punctuation.

+

+Descriptions are not self-referential; they do not include the thing they

+describe. Descriptions may contain upper case references to definitions

+but otherwise should be free of jargon.

+

+Descriptions may contain code and formulas, each bracketed by markup.

+

+Similar items may be grouped into topics. Topics may include subtopics.

+

+Each document begins with one or more indices that include the contents of

+that file. A class reference includes an index listing contained topics, 

+a separate listing for constructors, one for methods, and so on.

+

+Class methods contain a description, any parameters, any return value,

+an example, and any cross references.

+

+Each method must contain either one or more examples or markup indicating

+that there is no example.

+

+##

+

 Generate fiddle.json from all examples, including the ones you just wrote.

 Error checking is syntatic: starting keywords are closed, keywords have the

 correct parents.

diff --git a/site/user/api/SkCanvas_Reference.md b/site/user/api/SkCanvas_Reference.md
index 44942eee6a..a4a83ddfc3 100644
--- a/site/user/api/SkCanvas_Reference.md
+++ b/site/user/api/SkCanvas_Reference.md
@@ -773,7 +773,7 @@ may be nullptr</td>
 
 ### Return Value
 
-Address of pixels, or nullptr if inaccessible
+address of pixels, or nullptr if inaccessible
 
 ### Example
 
@@ -2132,7 +2132,7 @@ before it is combined with <a href="#Clip">Clip</a>.
 ### Parameters
 
 <table>  <tr>    <td><a name="SkCanvas_clipRect_rect"> <code><strong>rect </strong></code> </a></td> <td>
-Rectangle to combine with <a href="#Clip">Clip</a></td>
+<a href="undocumented#Rect">Rect</a> to combine with <a href="#Clip">Clip</a></td>
   </tr>  <tr>    <td><a name="SkCanvas_clipRect_op"> <code><strong>op </strong></code> </a></td> <td>
 <a href="#Op">Clip Op</a> to apply to <a href="#Clip">Clip</a></td>
   </tr>  <tr>    <td><a name="SkCanvas_clipRect_doAntiAlias"> <code><strong>doAntiAlias </strong></code> </a></td> <td>
@@ -2157,7 +2157,7 @@ Resulting <a href="#Clip">Clip</a> is aliased; pixels are fully contained by the
 ### Parameters
 
 <table>  <tr>    <td><a name="SkCanvas_clipRect_2_rect"> <code><strong>rect </strong></code> </a></td> <td>
-Rectangle to combine with <a href="#Clip">Clip</a></td>
+<a href="undocumented#Rect">Rect</a> to combine with <a href="#Clip">Clip</a></td>
   </tr>  <tr>    <td><a name="SkCanvas_clipRect_2_op"> <code><strong>op </strong></code> </a></td> <td>
 <a href="#Op">Clip Op</a> to apply to <a href="#Clip">Clip</a></td>
   </tr>
@@ -2181,7 +2181,7 @@ before it is combined with <a href="#Clip">Clip</a>.
 ### Parameters
 
 <table>  <tr>    <td><a name="SkCanvas_clipRect_3_rect"> <code><strong>rect </strong></code> </a></td> <td>
-Rectangle to combine with <a href="#Clip">Clip</a></td>
+<a href="undocumented#Rect">Rect</a> to combine with <a href="#Clip">Clip</a></td>
   </tr>  <tr>    <td><a name="SkCanvas_clipRect_3_doAntiAlias"> <code><strong>doAntiAlias </strong></code> </a></td> <td>
 true if <a href="#Clip">Clip</a> is to be anti-aliased</td>
   </tr>
@@ -2801,13 +2801,13 @@ and lines before drawing.
 ### Parameters
 
 <table>  <tr>    <td><a name="SkCanvas_drawPoints_mode"> <code><strong>mode </strong></code> </a></td> <td>
-Whether <a href="#SkCanvas_drawPoints_pts">pts</a> draws points or lines</td>
+whether <a href="#SkCanvas_drawPoints_pts">pts</a> draws points or lines</td>
   </tr>  <tr>    <td><a name="SkCanvas_drawPoints_count"> <code><strong>count </strong></code> </a></td> <td>
-The number of points in the array</td>
+number of points in the array</td>
   </tr>  <tr>    <td><a name="SkCanvas_drawPoints_pts"> <code><strong>pts </strong></code> </a></td> <td>
-Array of points to draw</td>
+array of points to draw</td>
   </tr>  <tr>    <td><a name="SkCanvas_drawPoints_paint"> <code><strong>paint </strong></code> </a></td> <td>
-Stroke, blend, color, and so on, used to draw</td>
+stroke, blend, color, and so on, used to draw</td>
   </tr>
 </table>
 
@@ -3904,7 +3904,7 @@ destination <a href="undocumented#Rect">Rect</a> of image to draw to</td>
 <a href="SkPaint_Reference#Paint">Paint</a> containing <a href="undocumented#Blend_Mode">Blend Mode</a>, <a href="undocumented#Color_Filter">Color Filter</a>, <a href="undocumented#Image_Filter">Image Filter</a>,
 and so on; or nullptr</td>
   </tr>  <tr>    <td><a name="SkCanvas_drawBitmapRect_2_constraint"> <code><strong>constraint </strong></code> </a></td> <td>
-Filter strictly within src or draw faster</td>
+sample strictly within src, or draw faster</td>
   </tr>
 </table>
 
@@ -4493,7 +4493,7 @@ byte length of <a href="#SkCanvas_drawTextOnPath_text">text</a> array</td>
 <a href="SkPath_Reference#Path">Path</a> providing <a href="#SkCanvas_drawTextOnPath_text">text</a> baseline</td>
   </tr>  <tr>    <td><a name="SkCanvas_drawTextOnPath_matrix"> <code><strong>matrix </strong></code> </a></td> <td>
 transform of glyphs before mapping to <a href="#SkCanvas_drawTextOnPath_path">path</a>; may be nullptr
-to use identity <a href="#Matrix">Matrix</a>.</td>
+to use identity <a href="#Matrix">Matrix</a></td>
   </tr>  <tr>    <td><a name="SkCanvas_drawTextOnPath_paint"> <code><strong>paint </strong></code> </a></td> <td>
 <a href="#SkCanvas_drawTextOnPath_text">text</a> size, blend, color, and so on, used to draw</td>
   </tr>
@@ -4814,7 +4814,7 @@ corners in top left, top right, bottom right, bottom left order.
 ### Parameters
 
 <table>  <tr>    <td><a name="SkCanvas_drawPatch_cubics"> <code><strong>cubics </strong></code> </a></td> <td>
-Cubic array, sharing common points</td>
+<a href="#Cubic">Path Cubic</a> array, sharing common points</td>
   </tr>  <tr>    <td><a name="SkCanvas_drawPatch_colors"> <code><strong>colors </strong></code> </a></td> <td>
 <a href="undocumented#Color">Color</a> array, one for each corner</td>
   </tr>  <tr>    <td><a name="SkCanvas_drawPatch_texCoords"> <code><strong>texCoords </strong></code> </a></td> <td>
@@ -4860,7 +4860,7 @@ corners in top left, top right, bottom right, bottom left order.
 ### Parameters
 
 <table>  <tr>    <td><a name="SkCanvas_drawPatch_2_cubics"> <code><strong>cubics </strong></code> </a></td> <td>
-Cubic array, sharing common points</td>
+<a href="#Cubic">Path Cubic</a> array, sharing common points</td>
   </tr>  <tr>    <td><a name="SkCanvas_drawPatch_2_colors"> <code><strong>colors </strong></code> </a></td> <td>
 <a href="undocumented#Color">Color</a> array, one for each corner</td>
   </tr>  <tr>    <td><a name="SkCanvas_drawPatch_2_texCoords"> <code><strong>texCoords </strong></code> </a></td> <td>
diff --git a/site/user/api/SkPaint_Reference.md b/site/user/api/SkPaint_Reference.md
index 236acdf5f5..94168b052e 100644
--- a/site/user/api/SkPaint_Reference.md
+++ b/site/user/api/SkPaint_Reference.md
@@ -3617,7 +3617,7 @@ Does not alter <a href="#SkPaint_setDrawLooper_drawLooper">drawLooper</a> <a hre
 ### Parameters
 
 <table>  <tr>    <td><a name="SkPaint_setDrawLooper_drawLooper"> <code><strong>drawLooper </strong></code> </a></td> <td>
-Iterates through drawing one or more time, altering <a href="#Paint">Paint</a></td>
+iterates through drawing one or more time, altering <a href="#Paint">Paint</a></td>
   </tr>
 </table>
 
@@ -4932,7 +4932,7 @@ returned intersections; may be nullptr</td>
 
 ### Return Value
 
-The number of intersections; may be zero
+number of intersections; may be zero
 
 ### Example
 
diff --git a/site/user/api/SkPath_Reference.md b/site/user/api/SkPath_Reference.md
index 13196dfbce..abd5e67644 100644
--- a/site/user/api/SkPath_Reference.md
+++ b/site/user/api/SkPath_Reference.md
@@ -161,7 +161,6 @@ Internally, <a href="#Path">Path</a> lazily computes metrics likes bounds and co
 | <a href="#SkPath_cubicTo">cubicTo</a> | Appends <a href="#Cubic">Cubic</a>. |
 | <a href="#SkPath_dump_2">dump</a> | Sends text representation using floats to stdout. |
 | <a href="#SkPath_dumpHex">dumpHex</a> | Sends text representation using hexadecimal to stdout. |
-| <a href="#SkPath_experimentalValidateRef">experimentalValidateRef</a> | Experimental; debugging only. |
 | <a href="#SkPath_getBounds">getBounds</a> | Returns maximum and minimum of <a href="#Point_Array">Point Array</a>. |
 | <a href="#SkPath_getConvexity">getConvexity</a> | Returns geometry convexity, computing if necessary. |
 | <a href="#SkPath_getConvexityOrUnknown">getConvexityOrUnknown</a> | Returns geometry convexity if known. |
@@ -395,7 +394,7 @@ pointers are not exposed.
 
 ### Return Value
 
-Copy of <a href="#Path">Path</a>
+copy of <a href="#Path">Path</a>
 
 ### Example
 
@@ -899,7 +898,7 @@ or if <a href="#Path">Path</a> has been altered since <a href="#Convexity">Conve
 
 ### Return Value
 
-Computed or stored <a href="#Convexity">Convexity</a>
+computed or stored <a href="#Convexity">Convexity</a>
 
 ### Example
 
@@ -923,7 +922,7 @@ Returns last computed <a href="#Convexity">Convexity</a>, or <a href="#SkPath_kU
 
 ### Return Value
 
-Stored <a href="#Convexity">Convexity</a>
+stored <a href="#Convexity">Convexity</a>
 
 ### Example
 
@@ -1337,6 +1336,9 @@ Test if <a href="undocumented#Line">Line</a> between <a href="undocumented#Point
 <a href="undocumented#Line">Line</a> with no length or that moves a very short distance is degenerate; it is
 treated as a point. 
 
+<a href="#SkPath_IsLineDegenerate_exact">exact</a> changes the equality test. If true, returns true only if <a href="#SkPath_IsLineDegenerate_p1">p1</a> equals <a href="#SkPath_IsLineDegenerate_p2">p2</a>.
+If false, returns true if <a href="#SkPath_IsLineDegenerate_p1">p1</a> equals or nearly equals <a href="#SkPath_IsLineDegenerate_p2">p2</a>.
+
 ### Parameters
 
 <table>  <tr>    <td><a name="SkPath_IsLineDegenerate_p1"> <code><strong>p1 </strong></code> </a></td> <td>
@@ -1344,8 +1346,7 @@ line start point</td>
   </tr>  <tr>    <td><a name="SkPath_IsLineDegenerate_p2"> <code><strong>p2 </strong></code> </a></td> <td>
 line end point</td>
   </tr>  <tr>    <td><a name="SkPath_IsLineDegenerate_exact"> <code><strong>exact </strong></code> </a></td> <td>
-If true, returns true only if <a href="#SkPath_IsLineDegenerate_p1">p1</a> equals <a href="#SkPath_IsLineDegenerate_p2">p2</a>. If false, returns true
-if <a href="#SkPath_IsLineDegenerate_p1">p1</a> equals or nearly equals <a href="#SkPath_IsLineDegenerate_p2">p2</a></td>
+if false, allow nearly equals</td>
   </tr>
 </table>
 
@@ -3144,7 +3145,7 @@ storage for <a href="#Quad">Quad</a> array</td>
 
 ### Return Value
 
-Number of <a href="#Quad">Quad</a> curves written to <a href="#SkPath_ConvertConicToQuads_pts">pts</a>
+number of <a href="#Quad">Quad</a> curves written to <a href="#SkPath_ConvertConicToQuads_pts">pts</a>
 
 ### Example
 
@@ -3313,7 +3314,7 @@ If <a href="#SkPath_addRect_2_dir">dir</a> is <a href="#SkPath_kCW_Direction">kC
   </tr>  <tr>    <td><a name="SkPath_addRect_2_dir"> <code><strong>dir </strong></code> </a></td> <td>
 <a href="#SkPath_Direction">Direction</a> to wind added contour</td>
   </tr>  <tr>    <td><a name="SkPath_addRect_2_start"> <code><strong>start </strong></code> </a></td> <td>
-Initial corner of <a href="undocumented#Rect">Rect</a> to add</td>
+initial corner of <a href="undocumented#Rect">Rect</a> to add</td>
   </tr>
 </table>
 
@@ -3670,7 +3671,7 @@ bounds and radii of rounded rectangle</td>
   </tr>  <tr>    <td><a name="SkPath_addRRect_2_dir"> <code><strong>dir </strong></code> </a></td> <td>
 <a href="#SkPath_Direction">Direction</a> to wind <a href="undocumented#Round_Rect">Round Rect</a></td>
   </tr>  <tr>    <td><a name="SkPath_addRRect_2_start"> <code><strong>start </strong></code> </a></td> <td>
-Index of initial point of <a href="undocumented#Round_Rect">Round Rect</a></td>
+index of initial point of <a href="undocumented#Round_Rect">Round Rect</a></td>
   </tr>
 </table>
 
@@ -3701,9 +3702,9 @@ Has no effect if <a href="#SkPath_addPoly_count">count</a> is less than one.
 ### Parameters
 
 <table>  <tr>    <td><a name="SkPath_addPoly_pts"> <code><strong>pts </strong></code> </a></td> <td>
-Array of <a href="undocumented#Line">Line</a> sharing end and start <a href="undocumented#Point">Point</a></td>
+array of <a href="undocumented#Line">Line</a> sharing end and start <a href="undocumented#Point">Point</a></td>
   </tr>  <tr>    <td><a name="SkPath_addPoly_count"> <code><strong>count </strong></code> </a></td> <td>
-Length of <a href="undocumented#Point">Point</a> array</td>
+length of <a href="undocumented#Point">Point</a> array</td>
   </tr>  <tr>    <td><a name="SkPath_addPoly_close"> <code><strong>close </strong></code> </a></td> <td>
 true to add <a href="undocumented#Line">Line</a> connecting <a href="#Contour">Contour</a> end and start</td>
   </tr>
@@ -3838,7 +3839,7 @@ added unaltered. If <a href="#SkPath_addPath_3_mode">mode</a> is <a href="#SkPat
 <table>  <tr>    <td><a name="SkPath_addPath_3_src"> <code><strong>src </strong></code> </a></td> <td>
 <a href="#Path">Path</a> <a href="#Verb">Verbs</a>, <a href="#Point">Points</a>, and <a href="#Weight">Conic Weights</a> to add</td>
   </tr>  <tr>    <td><a name="SkPath_addPath_3_matrix"> <code><strong>matrix </strong></code> </a></td> <td>
-Transform applied to <a href="#SkPath_addPath_3_src">src</a></td>
+<a href="#SkPath_transform">transform</a> applied to <a href="#SkPath_addPath_3_src">src</a></td>
   </tr>  <tr>    <td><a name="SkPath_addPath_3_mode"> <code><strong>mode </strong></code> </a></td> <td>
 <a href="#SkPath_kAppend_AddPathMode">kAppend AddPathMode</a> or <a href="#SkPath_kExtend_AddPathMode">kExtend AddPathMode</a></td>
   </tr>
@@ -4275,7 +4276,7 @@ void dump() const
 </pre>
 
 Writes text representation of <a href="#Path">Path</a> to stdout. The representation may be
-directly compiled as <a href="usingBookmaker#C">C</a>++ code. Floating point values are written
+directly compiled as <a href="undocumented#C">C</a>++ code. Floating point values are written
 with limited precision; it may not be possible to reconstruct original <a href="#Path">Path</a>
 from output.
 
@@ -4308,7 +4309,7 @@ void dumpHex() const
 </pre>
 
 Writes text representation of <a href="#Path">Path</a> to stdout. The representation may be
-directly compiled as <a href="usingBookmaker#C">C</a>++ code. Floating point values are written
+directly compiled as <a href="undocumented#C">C</a>++ code. Floating point values are written
 in hexadecimal to preserve their exact bit pattern. The output reconstructs the
 original <a href="#Path">Path</a>.
 
@@ -4538,34 +4539,14 @@ bool pathRefIsValid() const
 
 Returns if <a href="#Path">Path</a> data is consistent.
 
+To be deprecated soon.
+
 ### Return Value
 
 true if <a href="#Path">Path</a> data is consistent
 
 ---
 
-<a name="SkPath_validate"></a>
-## validate
-
-<pre style="padding: 1em 1em 1em 1em;width: 50em; background-color: #f0f0f0">
-void validate() const
-</pre>
-
-Asserts if <a href="#Path">Path</a> data is inconsistent; debug only.
-
----
-
-<a name="SkPath_experimentalValidateRef"></a>
-## experimentalValidateRef
-
-<pre style="padding: 1em 1em 1em 1em;width: 50em; background-color: #f0f0f0">
-void experimentalValidateRef() const
-</pre>
-
-Asserts if <a href="#Path">Path</a> data is inconsistent; debug only.
-
----
-
 # <a name="SkPath::Iter"></a> Class SkPath::Iter
 Iterates through <a href="#Verb_Array">Verb Array</a>, and associated <a href="#Point_Array">Point Array</a> and <a href="#Conic_Weight">Conic Weight</a>.
 Provides options to treat open <a href="#Contour">Contours</a> as closed, and to ignore
@@ -4729,7 +4710,9 @@ Verb next(SkPoint pts[4], bool doConsumeDegenerates = true, bool exact = false)
 
 Returns <a href="#SkPath_Iter_next">next</a> <a href="#SkPath_Verb">Verb</a> in <a href="#Verb_Array">Verb Array</a>, and advances <a href="#SkPath_Iter_Iter">Iter</a>.
 When <a href="#Verb_Array">Verb Array</a> is exhausted, returns <a href="#SkPath_kDone_Verb">kDone Verb</a>.
+
 Zero to four <a href="#Point">Points</a> are stored in <a href="#SkPath_Iter_next_pts">pts</a>, depending on the returned <a href="#SkPath_Verb">Verb</a>.
+
 If <a href="#SkPath_Iter_next_doConsumeDegenerates">doConsumeDegenerates</a> is true, skip consecutive <a href="#SkPath_kMove_Verb">kMove Verb</a> entries, returning
 only the last in the series; and skip very small <a href="#Line">Lines</a>, <a href="#Quad">Quads</a>, and <a href="#Conic">Conics</a>; and
 skip <a href="#SkPath_kClose_Verb">kClose Verb</a> following <a href="#SkPath_kMove_Verb">kMove Verb</a>.
@@ -4739,12 +4722,11 @@ if <a href="#SkPath_Iter_next_doConsumeDegenerates">doConsumeDegenerates</a> is
 ### Parameters
 
 <table>  <tr>    <td><a name="SkPath_Iter_next_pts"> <code><strong>pts </strong></code> </a></td> <td>
-Storage for <a href="undocumented#Point">Point</a> data describing returned <a href="#SkPath_Verb">Verb</a></td>
+storage for <a href="undocumented#Point">Point</a> data describing returned <a href="#SkPath_Verb">Verb</a></td>
   </tr>  <tr>    <td><a name="SkPath_Iter_next_doConsumeDegenerates"> <code><strong>doConsumeDegenerates </strong></code> </a></td> <td>
-If true, skip degenerate <a href="#Verb">Verbs</a></td>
+if true, skip degenerate <a href="#Verb">Verbs</a></td>
   </tr>  <tr>    <td><a name="SkPath_Iter_next_exact"> <code><strong>exact </strong></code> </a></td> <td>
-If true, skip zero length curves. Has no effect if <a href="#SkPath_Iter_next_doConsumeDegenerates">doConsumeDegenerates</a>
-is false</td>
+skip zero length curves</td>
   </tr>
 </table>
 
@@ -4993,7 +4975,7 @@ Zero to four <a href="#Point">Points</a> are stored in <a href="#SkPath_RawIter_
 ### Parameters
 
 <table>  <tr>    <td><a name="SkPath_RawIter_next_pts"> <code><strong>pts </strong></code> </a></td> <td>
-Storage for <a href="undocumented#Point">Point</a> data describing returned <a href="#SkPath_Verb">Verb</a></td>
+storage for <a href="undocumented#Point">Point</a> data describing returned <a href="#SkPath_Verb">Verb</a></td>
   </tr>
 </table>
 
diff --git a/site/user/api/usingBookmaker.md b/site/user/api/usingBookmaker.md
index 3ac0cdf312..f25f2abc94 100644
--- a/site/user/api/usingBookmaker.md
+++ b/site/user/api/usingBookmaker.md
@@ -4,7 +4,9 @@ usingBookmaker
 # <a name="Bookmaker"></a> Bookmaker
 How to use the <a href="#Bookmaker">Bookmaker</a> utility.
 
+Install<a href="usingBookmaker#Go">Go</a>https://golang.org/doc/installif needed.  
 Get the fiddle command line interface tool.
+By default this will appear in your home directory.
 
 <pre style="padding: 1em 1em 1em 1em;width: 44em; background-color: #f0f0f0">
 $ go get go.skia.org/infra/fiddle/go/fiddlecli</pre>
@@ -12,7 +14,7 @@ $ go get go.skia.org/infra/fiddle/go/fiddlecli</pre>
 Build <a href="#Bookmaker">Bookmaker</a>.
 
 <pre style="padding: 1em 1em 1em 1em;width: 44em; background-color: #f0f0f0">
-$ ninja -<a href="usingBookmaker#C">C</a> out/dir bookmaker</pre>
+$ ninja -<a href="undocumented#C">C</a> out/dir bookmaker</pre>
 
 Generate an starter <a href="#Bookmaker">Bookmaker</a> file from an existing include.
 This writes <a href="usingBookmaker#SkXXX">SkXXX</a>.bmh in the current directory, which is
@@ -24,6 +26,36 @@ $ ./out/dir/bookmaker -t -i include/core/<a href="usingBookmaker#SkXXX">SkXXX</a
 Copy <a href="usingBookmaker#SkXXX">SkXXX</a>.bmh to docs.
 Use your favorite editor to fill out docs/<a href="usingBookmaker#SkXXX">SkXXX</a>.bmh.
 
+## <a name="Style"></a> Style
+
+Documentation consists of cross references, descriptions, and examples.
+All structs, classes, enums, their members and methods, functions, and so on,
+require descriptions. Most also require examples.
+
+All methods and functions should include examples if practical.
+
+Descriptions start with an active verb. Descriptions are complete, punctuated
+sentences unless they describe parameters or return values. Parameters and
+returned values are described by phrases that start lower case and do not
+include trailing punctuation.
+
+Descriptions are not self-referential; they do not include the thing they
+describe. Descriptions may contain upper case references to definitions
+but otherwise should be free of jargon.
+
+Descriptions may contain code and formulas, each bracketed by markup.
+
+Similar items may be grouped into topics. Topics may include subtopics.
+
+Each document begins with one or more indices that include the contents of
+that file. A class reference includes an index listing contained topics, 
+a separate listing for constructors, one for methods, and so on.
+
+Class methods contain a description, any parameters, any return value,
+an example, and any cross references.
+
+Each method must contain either one or more examples or markup indicating
+that there is no example.
 Generate fiddle.json from all examples, including the ones you just wrote.
 Error checking is syntatic: starting keywords are closed, keywords have the
 correct parents.
diff --git a/tools/bookmaker/bookmaker.cpp b/tools/bookmaker/bookmaker.cpp
index 0c23c7720a..b3d3190b78 100644
--- a/tools/bookmaker/bookmaker.cpp
+++ b/tools/bookmaker/bookmaker.cpp
@@ -28,6 +28,7 @@ enum comments should be disallowed unless after #Enum and before first #Const
 trouble with aliases, plurals
     need to keep first letter of includeWriter @param / @return lowercase
     Quad -> quad, Quads -> quads
+check for summary containing all methods
  */
 
 static string normalized_name(string name) {
@@ -1028,16 +1029,8 @@ bool BmhParser::addDefinition(const char* defStart, bool hasEnd, MarkType markTy
                         return false;
                     }
                     if (MarkType::kParam == markType || MarkType::kReturn == markType) {
-                        const char* parmEndCheck = definition->fContentEnd;
-                        while (parmEndCheck < definition->fTerminator) {
-                            if (fMC == parmEndCheck[0]) {
-                                break;
-                            }
-                            if (' ' < parmEndCheck[0]) {
-                                this->reportError<bool>(
-                                        "use full end marker on multiline #Param and #Return");
-                            }
-                            ++parmEndCheck;
+                        if (!this->checkParamReturn(definition)) {
+                            return false;
                         }
                     }
                 } else {
@@ -1225,6 +1218,21 @@ bool BmhParser::checkExamples() const {
     return checkOK;
 }
 
+bool BmhParser::checkParamReturn(const Definition* definition) const {
+    const char* parmEndCheck = definition->fContentEnd;
+    while (parmEndCheck < definition->fTerminator) {
+        if (fMC == parmEndCheck[0]) {
+            break;
+        }
+        if (' ' < parmEndCheck[0]) {
+            this->reportError<bool>(
+                    "use full end marker on multiline #Param and #Return");
+        }
+        ++parmEndCheck;
+    }
+    return true;
+}
+
 bool BmhParser::childOf(MarkType markType) const {
     auto childError = [this](MarkType markType) -> bool {
         string errStr = "expected ";
@@ -2181,7 +2189,7 @@ int main(int argc, char** const argv) {
         return 0;
     }
     if ((FLAGS_include.isEmpty() || FLAGS_bmh.isEmpty()) && FLAGS_populate) {
-        SkDebugf("-r requires -b -i\n");
+        SkDebugf("-p requires -b -i\n");
         SkCommandLineFlags::PrintUsage();
         return 1;
     }
diff --git a/tools/bookmaker/bookmaker.h b/tools/bookmaker/bookmaker.h
index 0f0693fd77..71ff0d5dd6 100644
--- a/tools/bookmaker/bookmaker.h
+++ b/tools/bookmaker/bookmaker.h
@@ -1290,6 +1290,7 @@ public:
     bool addDefinition(const char* defStart, bool hasEnd, MarkType markType,
             const vector<string>& typeNameBuilder);
     bool checkExamples() const;
+    bool checkParamReturn(const Definition* definition) const;
     bool dumpExamples(const char* fiddleJsonFileName) const;
     bool childOf(MarkType markType) const;
     string className(MarkType markType);
@@ -1794,6 +1795,7 @@ private:
 
     string addReferences(const char* start, const char* end, BmhParser::Resolvable );
     bool buildRefFromFile(const char* fileName, const char* outDir);
+    bool checkParamReturnBody(const Definition* def) const;
     void childrenOut(const Definition* def, const char* contentStart);
     const Definition* isDefined(const TextParser& parser, const string& ref, bool report) const;
     string linkName(const Definition* ) const;
diff --git a/tools/bookmaker/mdOut.cpp b/tools/bookmaker/mdOut.cpp
index 744122a0a4..3718151e76 100644
--- a/tools/bookmaker/mdOut.cpp
+++ b/tools/bookmaker/mdOut.cpp
@@ -283,6 +283,26 @@ bool MdOut::buildRefFromFile(const char* name, const char* outDir) {
     return true;
 }
 
+bool MdOut::checkParamReturnBody(const Definition* def) const {
+    TextParser paramBody(def);
+    const char* descriptionStart = paramBody.fChar;
+    if (!islower(descriptionStart[0])) {
+        paramBody.skipToNonAlphaNum();
+        string ref = string(descriptionStart, paramBody.fChar - descriptionStart);
+        if (!this->isDefined(paramBody, ref, true)) {
+            string errorStr = MarkType::kReturn == def->fMarkType ? "return" : "param";
+            errorStr += " description must start with lower case";
+            paramBody.reportError(errorStr.c_str());
+            return false;
+        }
+    }
+    if ('.' == paramBody.fEnd[-1]) {
+        paramBody.reportError("make param description a phrase; should not end with period");
+        return false;
+    }
+    return true;
+}
+
 void MdOut::childrenOut(const Definition* def, const char* start) {
     const char* end;
     fLineCount = def->fLineCount;
@@ -719,6 +739,9 @@ void MdOut::markTypeOut(Definition* def) {
             const char* paramName = paramParser.fChar;
             paramParser.skipToSpace();
             string paramNameStr(paramName, (int) (paramParser.fChar - paramName));
+            if (!this->checkParamReturnBody(def)) {
+                return;
+            }
             string refNameStr = def->fParent->fFiddle + "_" + paramNameStr;
             fprintf(fOut, 
                     "    <td><a name=\"%s\"> <code><strong>%s </strong></code> </a></td> <td>",
@@ -731,6 +754,9 @@ void MdOut::markTypeOut(Definition* def) {
         case MarkType::kReturn:
             this->mdHeaderOut(3);
             fprintf(fOut, "Return Value");
+            if (!this->checkParamReturnBody(def)) {
+                return;
+            }
             this->lf(2);
             break;
         case MarkType::kRow: