From ca3ebcd724b4bc5ba8c79ef6471288dc09349af7 Mon Sep 17 00:00:00 2001 From: Cary Clark Date: Tue, 12 Dec 2017 11:22:38 -0500 Subject: fix fractured fiddles Latest run of Ravi's bot found a couple of new fiddle failures. Fix them. Yay, tools! Docs-Preview: https://skia.org/?cl=83944 Bug: skia:6898 Change-Id: I98ecef6b034363dfea88bcc9c710fb3017fc1c21 Reviewed-on: https://skia-review.googlesource.com/83944 Commit-Queue: Cary Clark Reviewed-by: Cary Clark --- docs/usingBookmaker.bmh | 40 ++++++++++++++++++++++++++++++++++++++-- 1 file changed, 38 insertions(+), 2 deletions(-) (limited to 'docs/usingBookmaker.bmh') diff --git a/docs/usingBookmaker.bmh b/docs/usingBookmaker.bmh index f0f79d213e..411fd7f379 100644 --- a/docs/usingBookmaker.bmh +++ b/docs/usingBookmaker.bmh @@ -64,6 +64,20 @@ 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. +It's difficult to think of a meaningful example for class destructors. +In cases like these, change the placeholder: + +###$ +$Code +#Example +$$ + +to: + +$Code +#NoExample +$$ +$$$# Descriptions start with an active verb. Descriptions are complete, punctuated sentences unless they describe parameters or return values. Parameters and @@ -71,8 +85,8 @@ 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. +describe. Descriptions may contain upper case or camel case references to +definitions but otherwise should be free of jargon. Descriptions may contain code and formulas, each bracketed by markup. @@ -88,6 +102,10 @@ an example, and any cross references. Each method must contain either one or more examples or markup indicating that there is no example. +After editing is complete, searching for "incomplete" should fail, +assuming "incomplete" is not the perfect word to use in a description or +example! + ## Generate fiddle.json from all examples, including the ones you just wrote. @@ -132,6 +150,24 @@ $ ./out/dir/bookmaker -p -b docs -i include/core/SkXXX.h to write the updated SkXXX.h to the current directory. +Once adding the file is complete, add the file to status.json in the +Completed section. You may add it to the InProgress section during +development, or leave status.json unchanged. + +If the new file has been added to status.json, you can run +any of the above commands with -a docs/status.json in place of +-b docs or -i includes. + +Complete rebuilding of all bookmaker output looks like: + +#Code + ./out/skia/bookmaker.exe -a docs/status.json -e fiddle.json + ~/go/bin/fiddlecli.exe --input fiddle.json --output fiddleout.json + ./out/skia/bookmaker.exe -a docs/status.json -f fiddleout.json -r site/user/api -c + ./out/skia/bookmaker.exe -a docs/status.json -x + ./out/skia/bookmaker.exe -a docs/status.json -p +## + #Subtopic Bugs Bookmaker bugs are tracked -- cgit v1.2.3