Cary Clark | 8032b98 | 2017-07-28 11:04:54 -0400 | [diff] [blame] | 1 | #External
|
| 2 | SkXXX
|
| 3 | bmh_SkXXX
|
| 4 | CL
|
Cary Clark | a523d2d | 2017-08-30 08:58:10 -0400 | [diff] [blame] | 5 | Go
|
Cary Clark | 8032b98 | 2017-07-28 11:04:54 -0400 | [diff] [blame] | 6 | Visual_Studio
|
| 7 | ##
|
| 8 |
|
| 9 | #Topic Bookmaker
|
| 10 |
|
| 11 | How to use the Bookmaker utility.
|
| 12 |
|
Cary Clark | 6fc5041 | 2017-09-21 12:31:06 -0400 | [diff] [blame] | 13 | Install
|
| 14 | #A Go # https://golang.org/doc/install ##
|
| 15 | if needed.
|
Cary Clark | 8032b98 | 2017-07-28 11:04:54 -0400 | [diff] [blame] | 16 | Get the fiddle command line interface tool.
|
Cary Clark | a523d2d | 2017-08-30 08:58:10 -0400 | [diff] [blame] | 17 | By default this will appear in your home directory.
|
Cary Clark | 8032b98 | 2017-07-28 11:04:54 -0400 | [diff] [blame] | 18 |
|
| 19 | #Code
|
| 20 | $ go get go.skia.org/infra/fiddle/go/fiddlecli
|
| 21 | ##
|
| 22 |
|
Cary Clark | bad5ad7 | 2017-08-03 17:14:08 -0400 | [diff] [blame] | 23 | Build Bookmaker.
|
Cary Clark | 8032b98 | 2017-07-28 11:04:54 -0400 | [diff] [blame] | 24 |
|
| 25 | #Code
|
Cary Clark | 8032b98 | 2017-07-28 11:04:54 -0400 | [diff] [blame] | 26 | $ ninja -C out/dir bookmaker
|
| 27 | ##
|
| 28 |
|
| 29 | Generate an starter Bookmaker file from an existing include.
|
Cary Clark | 8032b98 | 2017-07-28 11:04:54 -0400 | [diff] [blame] | 30 |
|
| 31 | #Code
|
Cary Clark | d0530ba | 2017-09-14 11:25:39 -0400 | [diff] [blame] | 32 | $ ./out/dir/bookmaker -i include/core/SkXXX.h -t docs
|
Cary Clark | 8032b98 | 2017-07-28 11:04:54 -0400 | [diff] [blame] | 33 | ##
|
| 34 |
|
Cary Clark | d0530ba | 2017-09-14 11:25:39 -0400 | [diff] [blame] | 35 | If a method or function has an unnamed parameter, bookmaker generates an error:
|
| 36 |
|
| 37 | #Code
|
| 38 | ###$
|
| 39 | C:/puregit/include/core/SkPixmap.h(208): error: #Method missing param name
|
| 40 | bool erase(const SkColor4f&, const SkIRect* subset = nullptr) const
|
| 41 | ^
|
| 42 | $$$#
|
| 43 | ##
|
| 44 |
|
| 45 | All parameters require names to allow markdown and doxygen documents to refer to
|
| 46 | them. After naming all parameters, check in the include before continuing.
|
| 47 |
|
| 48 | A successful run generates
|
| 49 | #Code
|
| 50 | docs/SkXXX_Reference.bmh
|
| 51 | ##
|
| 52 | .
|
| 53 |
|
| 54 | Next, use your favorite editor to fill out
|
| 55 | #Code
|
| 56 | docs/SkXXX_Reference.bmh
|
| 57 | ##
|
| 58 | .
|
Cary Clark | 8032b98 | 2017-07-28 11:04:54 -0400 | [diff] [blame] | 59 |
|
Cary Clark | a523d2d | 2017-08-30 08:58:10 -0400 | [diff] [blame] | 60 | #Subtopic Style
|
| 61 |
|
| 62 | Documentation consists of cross references, descriptions, and examples.
|
| 63 | All structs, classes, enums, their members and methods, functions, and so on,
|
| 64 | require descriptions. Most also require examples.
|
| 65 |
|
| 66 | All methods and functions should include examples if practical.
|
| 67 |
|
| 68 | Descriptions start with an active verb. Descriptions are complete, punctuated
|
| 69 | sentences unless they describe parameters or return values. Parameters and
|
| 70 | returned values are described by phrases that start lower case and do not
|
| 71 | include trailing punctuation.
|
| 72 |
|
| 73 | Descriptions are not self-referential; they do not include the thing they
|
| 74 | describe. Descriptions may contain upper case references to definitions
|
| 75 | but otherwise should be free of jargon.
|
| 76 |
|
| 77 | Descriptions may contain code and formulas, each bracketed by markup.
|
| 78 |
|
| 79 | Similar items may be grouped into topics. Topics may include subtopics.
|
| 80 |
|
| 81 | Each document begins with one or more indices that include the contents of
|
| 82 | that file. A class reference includes an index listing contained topics,
|
| 83 | a separate listing for constructors, one for methods, and so on.
|
| 84 |
|
| 85 | Class methods contain a description, any parameters, any return value,
|
| 86 | an example, and any cross references.
|
| 87 |
|
| 88 | Each method must contain either one or more examples or markup indicating
|
| 89 | that there is no example.
|
| 90 |
|
| 91 | ##
|
| 92 |
|
Cary Clark | 8032b98 | 2017-07-28 11:04:54 -0400 | [diff] [blame] | 93 | Generate fiddle.json from all examples, including the ones you just wrote.
|
| 94 | Error checking is syntatic: starting keywords are closed, keywords have the
|
| 95 | correct parents.
|
| 96 | If you run Bookmaker inside Visual_Studio, you can click on errors and it
|
| 97 | will take you to the source line in question.
|
| 98 |
|
| 99 | #Code
|
Cary Clark | bad5ad7 | 2017-08-03 17:14:08 -0400 | [diff] [blame] | 100 | $ ./out/dir/bookmaker -e fiddle.json -b docs
|
Cary Clark | 8032b98 | 2017-07-28 11:04:54 -0400 | [diff] [blame] | 101 | ##
|
| 102 |
|
| 103 | Once complete, run fiddlecli to generate the example hashes.
|
| 104 | Errors are contained by the output but aren't reported yet.
|
| 105 |
|
| 106 | #Code
|
| 107 | $ $GOPATH/bin/fiddlecli --input fiddle.json --output fiddleout.json
|
| 108 | ##
|
| 109 |
|
| 110 | Generate bmh_SkXXX.md from SkXXX.bmh and fiddleout.json.
|
| 111 | Error checking includes: undefined references, fiddle compiler errors,
|
| 112 | missing or mismatched printf output.
|
| 113 | Again, you can click on any errors inside Visual_Studio.
|
| 114 |
|
| 115 | #Code
|
Cary Clark | bad5ad7 | 2017-08-03 17:14:08 -0400 | [diff] [blame] | 116 | $ ./out/dir/bookmaker -r site/user/api -b docs -f fiddleout.json
|
Cary Clark | 8032b98 | 2017-07-28 11:04:54 -0400 | [diff] [blame] | 117 | ##
|
| 118 |
|
| 119 | The original include may have changed since you started creating the markdown.
|
| 120 | Check to see if it is up to date.
|
| 121 | This reports if a method no longer exists or its parameters have changed.
|
| 122 |
|
| 123 | #Code
|
Cary Clark | bad5ad7 | 2017-08-03 17:14:08 -0400 | [diff] [blame] | 124 | $ ./out/dir/bookmaker -x -b docs/SkXXX.bmh -i include/core/SkXXX.h
|
Cary Clark | 8032b98 | 2017-07-28 11:04:54 -0400 | [diff] [blame] | 125 | ##
|
| 126 |
|
Cary Clark | d0530ba | 2017-09-14 11:25:39 -0400 | [diff] [blame] | 127 | Generate an updated include header. Run:
|
Cary Clark | bad5ad7 | 2017-08-03 17:14:08 -0400 | [diff] [blame] | 128 |
|
| 129 | #Code
|
| 130 | $ ./out/dir/bookmaker -p -b docs -i include/core/SkXXX.h
|
Cary Clark | 8032b98 | 2017-07-28 11:04:54 -0400 | [diff] [blame] | 131 | ##
|
| 132 |
|
Cary Clark | d0530ba | 2017-09-14 11:25:39 -0400 | [diff] [blame] | 133 | to write the updated SkXXX.h to the current directory.
|
| 134 |
|
Cary Clark | bad5ad7 | 2017-08-03 17:14:08 -0400 | [diff] [blame] | 135 | #Subtopic Bugs
|
| 136 |
|
Cary Clark | 6fc5041 | 2017-09-21 12:31:06 -0400 | [diff] [blame] | 137 | Bookmaker bugs are tracked
|
| 138 | #A here # bug.skia.org/6898 ##
|
| 139 | .
|
Cary Clark | bad5ad7 | 2017-08-03 17:14:08 -0400 | [diff] [blame] | 140 |
|
Cary Clark | 8032b98 | 2017-07-28 11:04:54 -0400 | [diff] [blame] | 141 | ##
|
| 142 |
|
| 143 | #Topic Bookmaker ##
|