blob: 236c16d7c51499fa69e20b663dc1a92958b2340b [file] [log] [blame]
Ben Wagner29380bd2017-10-09 14:43:00 -04001#External
2SkXXX
Cary Clark7cfcbca2018-01-04 16:11:51 -05003SkIRect_Reference
4SkSurface_Reference
5SkSurface.h
Ben Wagner29380bd2017-10-09 14:43:00 -04006CL
7Go
8Visual_Studio
Cary Clarkc7924c92017-12-14 08:28:46 -05009Completed InProgress
Ben Wagner29380bd2017-10-09 14:43:00 -040010##
11
12#Topic Bookmaker
13
Cary Clarkac47b882018-01-11 10:35:44 -050014How to use the Bookmaker utility.
15
Cary Clark7cfcbca2018-01-04 16:11:51 -050016#Subtopic Broken_Build
17
Cary Clark682c58d2018-05-16 07:07:07 -040018If the
Cary Clark7cfcbca2018-01-04 16:11:51 -050019#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
Cary Clarkac47b882018-01-11 10:35:44 -050029If 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()
Cary Clarkac47b882018-01-11 10:35:44 -050035#Deprecated
36##
Cary Clark4855f782018-02-06 09:41:53 -050037$$
Cary Clarkac47b882018-01-11 10:35:44 -050038
Cary Clark4855f782018-02-06 09:41:53 -050039Use
40
41$Code
42##Deprecated soon
43$$
44
45if the change is soon to be deprecated.
46
Cary Clarkac47b882018-01-11 10:35:44 -050047$$$#
Cary Clarkac47b882018-01-11 10:35:44 -050048
Cary Clark7cfcbca2018-01-04 16:11:51 -050049To regenerate the documentation, follow the Installing and Regenerate steps below.
50
51If the
Cary Clarkf5404bb2018-01-05 12:10:09 -050052#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.
Cary Clark7cfcbca2018-01-04 16:11:51 -050064
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
Cary Clarkac47b882018-01-11 10:35:44 -050096#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 ##
Ben Wagner29380bd2017-10-09 14:43:00 -0400115
Cary Clark7cfcbca2018-01-04 16:11:51 -0500116#Subtopic Installing
117
Ben Wagner29380bd2017-10-09 14:43:00 -0400118Install
119#A Go # https://golang.org/doc/install ##
Cary Clark7cfcbca2018-01-04 16:11:51 -0500120 if needed.
Ben Wagner29380bd2017-10-09 14:43:00 -0400121Get the fiddle command line interface tool.
122By default this will appear in your home directory.
123
124#Code
Ruiqi Mao94d57c42018-07-02 15:20:10 -0400125$ go get go.skia.org/infra/fiddlek/go/fiddlecli
Ben Wagner29380bd2017-10-09 14:43:00 -0400126##
127
128Build Bookmaker.
129
130#Code
131$ ninja -C out/dir bookmaker
132##
133
Cary Clark7cfcbca2018-01-04 16:11:51 -0500134#Subtopic Installing ##
135
136#Subtopic Regenerate
137
138Complete rebuilding of all bookmaker output looks like:
139
140#Code
Cary Clarkab2621d2018-01-30 10:08:57 -0500141$ ./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
Cary Clark7cfcbca2018-01-04 16:11:51 -0500146##
147
148#Subtopic Regenerate ##
149
150#Subtopic New_Documentation
151
Ben Wagner29380bd2017-10-09 14:43:00 -0400152Generate 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
Cary Clark7cfcbca2018-01-04 16:11:51 -0500183##
184
Ben Wagner29380bd2017-10-09 14:43:00 -0400185#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.
Cary Clarkca3ebcd2017-12-12 11:22:38 -0500192It'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$$$#
Ben Wagner29380bd2017-10-09 14:43:00 -0400206
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
Cary Clarkca3ebcd2017-12-12 11:22:38 -0500213describe. Descriptions may contain upper case or camel case references to
214definitions but otherwise should be free of jargon.
Ben Wagner29380bd2017-10-09 14:43:00 -0400215
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
Cary Clark7cfcbca2018-01-04 16:11:51 -0500221that file. A class reference includes an index listing contained topics,
Ben Wagner29380bd2017-10-09 14:43:00 -0400222a 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
Cary Clarkca3ebcd2017-12-12 11:22:38 -0500230After editing is complete, searching for "incomplete" should fail,
231assuming "incomplete" is not the perfect word to use in a description or
232example!
233
Cary Clark7cfcbca2018-01-04 16:11:51 -0500234#Subtopic Style ##
235
236#Subtopic Adding_Documentation
Ben Wagner29380bd2017-10-09 14:43:00 -0400237
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
Cary Clark7cfcbca2018-01-04 16:11:51 -0500255Generate SkXXX.md from SkXXX.bmh and fiddleout.json.
Ben Wagner29380bd2017-10-09 14:43:00 -0400256Error 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
Cary Clarkca3ebcd2017-12-12 11:22:38 -0500280Once 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
Cary Clark7cfcbca2018-01-04 16:11:51 -0500288#Subtopic Adding_Documentation ##
Cary Clarkca3ebcd2017-12-12 11:22:38 -0500289
Ben Wagner29380bd2017-10-09 14:43:00 -0400290#Subtopic Bugs
291
292Bookmaker bugs are tracked
Cary Clark682c58d2018-05-16 07:07:07 -0400293#A here # https://bug.skia.org/6898 ##
Ben Wagner29380bd2017-10-09 14:43:00 -0400294.
295
296##
297
298#Topic Bookmaker ##