| #External |
| SkXXX |
| SkIRect_Reference |
| SkSurface_Reference |
| SkSurface.h |
| CL |
| Go |
| Visual_Studio |
| Completed InProgress |
| ## |
| |
| #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. |
| 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 |
| ## |
| |
| Build Bookmaker. |
| |
| #Code |
| $ 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 |
| $ ./out/dir/bookmaker -i include/core/SkXXX.h -t docs |
| ## |
| |
| If a method or function has an unnamed parameter, bookmaker generates an error: |
| |
| #Code |
| ###$ |
| C:/puregit/include/core/SkPixmap.h(208): error: #Method missing param name |
| bool erase(const SkColor4f&, const SkIRect* subset = nullptr) const |
| ^ |
| $$$# |
| ## |
| |
| All parameters require names to allow markdown and doxygen documents to refer to |
| them. After naming all parameters, check in the include before continuing. |
| |
| A successful run generates |
| #Code |
| docs/SkXXX_Reference.bmh |
| ## |
| . |
| |
| Next, use your favorite editor to fill out |
| #Code |
| docs/SkXXX_Reference.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. |
| 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 |
| 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 or camel 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. |
| |
| After editing is complete, searching for "incomplete" should fail, |
| 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 |
| correct parents. |
| If you run Bookmaker inside Visual_Studio, you can click on errors and it |
| will take you to the source line in question. |
| |
| #Code |
| $ ./out/dir/bookmaker -e fiddle.json -b docs |
| ## |
| |
| Once complete, run fiddlecli to generate the example hashes. |
| Errors are contained by the output but aren't reported yet. |
| |
| #Code |
| $ $GOPATH/bin/fiddlecli --input fiddle.json --output 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. |
| |
| #Code |
| $ ./out/dir/bookmaker -r site/user/api -b docs -f fiddleout.json |
| ## |
| |
| The original include may have changed since you started creating the markdown. |
| Check to see if it is up to date. |
| This reports if a method no longer exists or its parameters have changed. |
| |
| #Code |
| $ ./out/dir/bookmaker -x -b docs/SkXXX.bmh -i include/core/SkXXX.h |
| ## |
| |
| Generate an updated include header. Run: |
| |
| #Code |
| $ ./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. |
| |
| #Subtopic Adding_Documentation ## |
| |
| #Subtopic Bugs |
| |
| Bookmaker bugs are tracked |
| #A here # bug.skia.org/6898 ## |
| . |
| |
| ## |
| |
| #Topic Bookmaker ## |