limit bookmaker status output
streamline 'working as intended' output
notify when output changed
fix bug which appended output incorrectly to SkBitmap.h
fix bug that hid bad SkSurface.h from detection
Docs-Preview: https://skia.org/?cl=90162
Bug: skia:6898
Change-Id: I067cfe5bbad706345fb5cd540cdc3835ce22d822
Reviewed-on: https://skia-review.googlesource.com/90162
Commit-Queue: Cary Clark <caryclark@skia.org>
Reviewed-by: Cary Clark <caryclark@skia.org>
diff --git a/docs/usingBookmaker.bmh b/docs/usingBookmaker.bmh
index 4d44d73..470dd3c 100644
--- a/docs/usingBookmaker.bmh
+++ b/docs/usingBookmaker.bmh
@@ -1,6 +1,8 @@
#External
SkXXX
-bmh_SkXXX
+SkIRect_Reference
+SkSurface_Reference
+SkSurface.h
CL
Go
Visual_Studio
@@ -9,11 +11,73 @@
#Topic Bookmaker
+#Subtopic Broken_Build
+
+If the
+#A Housekeeper-PerCommit-Bookmaker # https://status.skia.org/repo/skia?filter=search&search_value=Housekeeper-PerCommit-Bookmaker ##
+ bot is red, the bot has detected that the files in docs and include/core differ.
+
+The bot output describes what changed.
+
+To fix this, edit the docs file corresponding to the changed include file.
+
+For instance, if the change was made to SkIRect, edit docs/SkIRect_Reference.bmh.
+Checking in the edited docs/SkIRect_Reference.bmh will fix the bot.
+
+To regenerate the documentation, follow the Installing and Regenerate steps below.
+
+If the
+#A Housekeeper-Nightly-Bookmaker # https://status.skia.org/repo/skia?filter=search&search_value=Housekeeper-Nightly-Bookmaker ##
+ bot is red, one of several things may have gone wrong:
+
+#List
+# A change to include broke documentation examples. ##
+# Something changed the examples that output text. ##
+# Some interface was added, deleted, edited. ##
+# Documentation is malformed. ##
+##
+
+The bot output describes what changed, and includes the file and line
+where the error occurred.
+
+To regenerate the documentation, follow the Installing and Regenerate steps below.
+
+#Subtopic Broken_Build ##
+
+#Subtopic Editing_Comments
+
+Edit docs instead of include/core files to update comments if possible.
+
+The Bookmaker bots do not complain if the docs file does not match the
+corresponding include comments. Running Bookmaker include generation will
+report when docs and includes comments do not match.
+
+For instance, if include/core/SkSurface.h comments do not match
+docs/SkSurface_Reference.bmh, running:
+
+#Code
+$ ./out/dir/bookmaker -b docs -i include/core/SkSurface.h -p
+##
+
+generates
+
+#Code
+wrote updated SkSurface.h
+##
+
+The updated SkSurface.h is written to the root to avoid subsequent runs of
+Bookmaker from recompiling. if SkSurface.h was not changed, it is not written,
+and Bookmaker will not generate any output.
+
+#Subtopic Editing_Comments ##
+
How to use the Bookmaker utility.
+#Subtopic Installing
+
Install
#A Go # https://golang.org/doc/install ##
- if needed.
+ if needed.
Get the fiddle command line interface tool.
By default this will appear in your home directory.
@@ -27,6 +91,24 @@
$ ninja -C out/dir bookmaker
##
+#Subtopic Installing ##
+
+#Subtopic Regenerate
+
+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 Regenerate ##
+
+#Subtopic New_Documentation
+
Generate an starter Bookmaker file from an existing include.
#Code
@@ -58,6 +140,8 @@
##
.
+##
+
#Subtopic Style
Documentation consists of cross references, descriptions, and examples.
@@ -94,7 +178,7 @@
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,
+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,
@@ -107,7 +191,9 @@
assuming "incomplete" is not the perfect word to use in a description or
example!
-##
+#Subtopic Style ##
+
+#Subtopic Adding_Documentation
Generate fiddle.json from all examples, including the ones you just wrote.
Error checking is syntatic: starting keywords are closed, keywords have the
@@ -126,7 +212,7 @@
$ $GOPATH/bin/fiddlecli --input fiddle.json --output fiddleout.json
##
-Generate bmh_SkXXX.md from SkXXX.bmh and fiddleout.json.
+Generate SkXXX.md from SkXXX.bmh and fiddleout.json.
Error checking includes: undefined references, fiddle compiler errors,
missing or mismatched printf output.
Again, you can click on any errors inside Visual_Studio.
@@ -159,15 +245,7 @@
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 Adding_Documentation ##
#Subtopic Bugs