1#External 2SkXXX 3SkIRect_Reference 4SkSurface_Reference 5SkSurface.h 6CL 7Go 8Visual_Studio 9Completed InProgress 10## 11 12#Topic Bookmaker 13 14How to use the Bookmaker utility. 15 16#Subtopic Broken_Build 17 18If the 19#A Housekeeper-PerCommit-Bookmaker # https://status.skia.org/repo/skia?filter=search&search_value=Housekeeper-PerCommit-Bookmaker ## 20 bot is red, the bot has detected that the files in docs and include/core differ. 21 22The bot output describes what changed. 23 24To fix this, edit the docs file corresponding to the changed include file. 25 26For instance, if the change was made to SkIRect, edit docs/SkIRect_Reference.bmh. 27Checking in the edited docs/SkIRect_Reference.bmh will fix the bot. 28 29If the interface is deprecated, but still present in the interface, mark-up the 30documentation to be deprecated as well. 31 32#Code 33###$ 34#Method void someMethodThatIsNowDeprecated() 35 36#Deprecated 37## 38 39## 40$$$# 41## 42 43To regenerate the documentation, follow the Installing and Regenerate steps below. 44 45If the 46#A Housekeeper-Nightly-Bookmaker # https://status.skia.org/repo/skia?filter=search&search_value=Housekeeper-Nightly-Bookmaker ## 47 bot is red, one of several things may have gone wrong: 48 49#List 50# A change to include broke documentation examples. ## 51# Something changed the examples that output text. ## 52# Some interface was added, deleted, edited. ## 53# Documentation is malformed. ## 54## 55 56The bot output describes what changed, and includes the file and line 57where the error occurred. 58 59To regenerate the documentation, follow the Installing and Regenerate steps below. 60 61#Subtopic Broken_Build ## 62 63#Subtopic Editing_Comments 64 65Edit docs instead of include/core files to update comments if possible. 66 67The Bookmaker bots do not complain if the docs file does not match the 68corresponding include comments. Running Bookmaker include generation will 69report when docs and includes comments do not match. 70 71For instance, if include/core/SkSurface.h comments do not match 72docs/SkSurface_Reference.bmh, running: 73 74#Code 75$ ./out/dir/bookmaker -b docs -i include/core/SkSurface.h -p 76## 77 78generates 79 80#Code 81wrote updated SkSurface.h 82## 83 84The updated SkSurface.h is written to the root to avoid subsequent runs of 85Bookmaker from recompiling. if SkSurface.h was not changed, it is not written, 86and Bookmaker will not generate any output. 87 88#Subtopic Editing_Comments ## 89 90#Subtopic Broken_Example 91 92An example may cause Bookmaker or a bot running Bookmaker to fail if it can't 93be compiled by fiddle. If the example cannot be fixed, it can be commented out 94by changing 95###$ 96$Code 97$Literal 98#Example 99$Code $$ 100to 101$Code 102#NoExample 103$Code $$ 104$$$# 105. The disabled example can contain additional markup, 106which will be ignored. 107 108#Subtopic Broken_Example ## 109 110#Subtopic Installing 111 112Install 113#A Go # https://golang.org/doc/install ## 114 if needed. 115Get the fiddle command line interface tool. 116By default this will appear in your home directory. 117 118#Code 119$ go get go.skia.org/infra/fiddle/go/fiddlecli 120## 121 122Build Bookmaker. 123 124#Code 125$ ninja -C out/dir bookmaker 126## 127 128#Subtopic Installing ## 129 130#Subtopic Regenerate 131 132Complete rebuilding of all bookmaker output looks like: 133 134#Code 135$ ./out/skia/bookmaker -a docs/status.json -e fiddle.json 136$ ~/go/bin/fiddlecli --input fiddle.json --output fiddleout.json 137$ ./out/skia/bookmaker -a docs/status.json -f fiddleout.json -r site/user/api -c 138$ ./out/skia/bookmaker -a docs/status.json -x 139$ ./out/skia/bookmaker -a docs/status.json -p 140## 141 142#Subtopic Regenerate ## 143 144#Subtopic New_Documentation 145 146Generate an starter Bookmaker file from an existing include. 147 148#Code 149$ ./out/dir/bookmaker -i include/core/SkXXX.h -t docs 150## 151 152If a method or function has an unnamed parameter, bookmaker generates an error: 153 154#Code 155###$ 156C:/puregit/include/core/SkPixmap.h(208): error: #Method missing param name 157bool erase(const SkColor4f&, const SkIRect* subset = nullptr) const 158 ^ 159$$$# 160## 161 162All parameters require names to allow markdown and doxygen documents to refer to 163them. After naming all parameters, check in the include before continuing. 164 165A successful run generates 166#Code 167docs/SkXXX_Reference.bmh 168## 169. 170 171Next, use your favorite editor to fill out 172#Code 173docs/SkXXX_Reference.bmh 174## 175. 176 177## 178 179#Subtopic Style 180 181Documentation consists of cross references, descriptions, and examples. 182All structs, classes, enums, their members and methods, functions, and so on, 183require descriptions. Most also require examples. 184 185All methods and functions should include examples if practical. 186It's difficult to think of a meaningful example for class destructors. 187In cases like these, change the placeholder: 188 189###$ 190$Code 191#Example 192$$ 193 194to: 195 196$Code 197#NoExample 198$$ 199$$$# 200 201Descriptions start with an active verb. Descriptions are complete, punctuated 202sentences unless they describe parameters or return values. Parameters and 203returned values are described by phrases that start lower case and do not 204include trailing punctuation. 205 206Descriptions are not self-referential; they do not include the thing they 207describe. Descriptions may contain upper case or camel case references to 208definitions but otherwise should be free of jargon. 209 210Descriptions may contain code and formulas, each bracketed by markup. 211 212Similar items may be grouped into topics. Topics may include subtopics. 213 214Each document begins with one or more indices that include the contents of 215that file. A class reference includes an index listing contained topics, 216a separate listing for constructors, one for methods, and so on. 217 218Class methods contain a description, any parameters, any return value, 219an example, and any cross references. 220 221Each method must contain either one or more examples or markup indicating 222that there is no example. 223 224After editing is complete, searching for "incomplete" should fail, 225assuming "incomplete" is not the perfect word to use in a description or 226example! 227 228#Subtopic Style ## 229 230#Subtopic Adding_Documentation 231 232Generate fiddle.json from all examples, including the ones you just wrote. 233Error checking is syntatic: starting keywords are closed, keywords have the 234correct parents. 235If you run Bookmaker inside Visual_Studio, you can click on errors and it 236will take you to the source line in question. 237 238#Code 239$ ./out/dir/bookmaker -e fiddle.json -b docs 240## 241 242Once complete, run fiddlecli to generate the example hashes. 243Errors are contained by the output but aren't reported yet. 244 245#Code 246$ $GOPATH/bin/fiddlecli --input fiddle.json --output fiddleout.json 247## 248 249Generate SkXXX.md from SkXXX.bmh and fiddleout.json. 250Error checking includes: undefined references, fiddle compiler errors, 251missing or mismatched printf output. 252Again, you can click on any errors inside Visual_Studio. 253 254#Code 255$ ./out/dir/bookmaker -r site/user/api -b docs -f fiddleout.json 256## 257 258The original include may have changed since you started creating the markdown. 259Check to see if it is up to date. 260This reports if a method no longer exists or its parameters have changed. 261 262#Code 263$ ./out/dir/bookmaker -x -b docs/SkXXX.bmh -i include/core/SkXXX.h 264## 265 266Generate an updated include header. Run: 267 268#Code 269$ ./out/dir/bookmaker -p -b docs -i include/core/SkXXX.h 270## 271 272to write the updated SkXXX.h to the current directory. 273 274Once adding the file is complete, add the file to status.json in the 275Completed section. You may add it to the InProgress section during 276development, or leave status.json unchanged. 277 278If the new file has been added to status.json, you can run 279any of the above commands with -a docs/status.json in place of 280-b docs or -i includes. 281 282#Subtopic Adding_Documentation ## 283 284#Subtopic Bugs 285 286Bookmaker bugs are tracked 287#A here # bug.skia.org/6898 ## 288. 289 290## 291 292#Topic Bookmaker ## 293