Ben Wagner | 29380bd | 2017-10-09 14:43:00 -0400 | [diff] [blame] | 1 | #External |
| 2 | SkXXX |
| 3 | bmh_SkXXX |
| 4 | CL |
| 5 | Go |
| 6 | Visual_Studio |
| 7 | ## |
| 8 | |
| 9 | #Topic Bookmaker |
| 10 | |
| 11 | How to use the Bookmaker utility. |
| 12 | |
| 13 | Install |
| 14 | #A Go # https://golang.org/doc/install ## |
| 15 | if needed. |
| 16 | Get the fiddle command line interface tool. |
| 17 | By default this will appear in your home directory. |
| 18 | |
| 19 | #Code |
| 20 | $ go get go.skia.org/infra/fiddle/go/fiddlecli |
| 21 | ## |
| 22 | |
| 23 | Build Bookmaker. |
| 24 | |
| 25 | #Code |
| 26 | $ ninja -C out/dir bookmaker |
| 27 | ## |
| 28 | |
| 29 | Generate an starter Bookmaker file from an existing include. |
| 30 | |
| 31 | #Code |
| 32 | $ ./out/dir/bookmaker -i include/core/SkXXX.h -t docs |
| 33 | ## |
| 34 | |
| 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 | . |
| 59 | |
| 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 | |
| 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 |
| 100 | $ ./out/dir/bookmaker -e fiddle.json -b docs |
| 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 |
| 116 | $ ./out/dir/bookmaker -r site/user/api -b docs -f fiddleout.json |
| 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 |
| 124 | $ ./out/dir/bookmaker -x -b docs/SkXXX.bmh -i include/core/SkXXX.h |
| 125 | ## |
| 126 | |
| 127 | Generate an updated include header. Run: |
| 128 | |
| 129 | #Code |
| 130 | $ ./out/dir/bookmaker -p -b docs -i include/core/SkXXX.h |
| 131 | ## |
| 132 | |
| 133 | to write the updated SkXXX.h to the current directory. |
| 134 | |
| 135 | #Subtopic Bugs |
| 136 | |
| 137 | Bookmaker bugs are tracked |
| 138 | #A here # bug.skia.org/6898 ## |
| 139 | . |
| 140 | |
| 141 | ## |
| 142 | |
| 143 | #Topic Bookmaker ## |