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