diff options
| -rw-r--r-- | docs/SkCanvas_Reference.bmh | 24 | ||||
| -rw-r--r-- | docs/SkPaint_Reference.bmh | 4 | ||||
| -rw-r--r-- | docs/SkPath_Reference.bmh | 41 | ||||
| -rw-r--r-- | docs/undocumented.bmh | 2 | ||||
| -rw-r--r-- | docs/usingBookmaker.bmh | 37 | ||||
| -rw-r--r-- | site/user/api/SkCanvas_Reference.md | 24 | ||||
| -rw-r--r-- | site/user/api/SkPaint_Reference.md | 4 | ||||
| -rw-r--r-- | site/user/api/SkPath_Reference.md | 64 | ||||
| -rw-r--r-- | site/user/api/usingBookmaker.md | 34 | ||||
| -rw-r--r-- | tools/bookmaker/bookmaker.cpp | 30 | ||||
| -rw-r--r-- | tools/bookmaker/bookmaker.h | 2 | ||||
| -rw-r--r-- | tools/bookmaker/mdOut.cpp | 26 |
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: |