docs/usingBookmaker.bmh - platform/external/skia - Gitiles

 #External
 SkXXX
 SkIRect_Reference
 SkSurface_Reference
 SkSurface.h
 CL
 Go
 Visual_Studio
 Completed InProgress
 ##

 #Topic Bookmaker

 How to use the Bookmaker utility.

 #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.

 If the interface is deprecated, but still present in the interface, mark-up the
 documentation to be deprecated as well.

 #Code
 ###$
 #Method void someMethodThatIsNowDeprecated()
 #Deprecated
 ##
 $$

 Use

 $Code
 ##Deprecated soon
 $$

 if the change is soon to be deprecated.

 $$$#

 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 ##

 #Subtopic Broken_Example

 An example may cause Bookmaker or a bot running Bookmaker to fail if it can't
 be compiled by fiddle. If the example cannot be fixed, it can be commented out
 by changing
 ###$
 $Code
 $Literal
 #Example
 $Code $$
 to
 $Code
 #NoExample
 $Code $$
 $$$#
 . The disabled example can contain additional markup,
 which will be ignored.

 #Subtopic Broken_Example ##

 #Subtopic Installing

 Install
 #A Go # https://golang.org/doc/install ##
  if needed.
 Check the version. The resuls should be 1.10 or greater.

 #Code
 $ go version
 ##

 Get the fiddle command line interface tool.
 By default this will appear in your home directory.

 #Code
 $ go get go.skia.org/infra/fiddlek/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 -a docs/status.json -e fiddle.json
 $ ~/go/bin/fiddlecli --input fiddle.json --output fiddleout.json
 $ ./out/skia/bookmaker -a docs/status.json -f fiddleout.json -r site/user/api -c
 $ ./out/skia/bookmaker -a docs/status.json -x
 $ ./out/skia/bookmaker -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 # https://bug.skia.org/6898 ##
 .

 ##

 #Topic Bookmaker ##
	#External
	SkXXX
	SkIRect_Reference
	SkSurface_Reference
	SkSurface.h
	CL
	Go
	Visual_Studio
	Completed InProgress
	##

	#Topic Bookmaker

	How to use the Bookmaker utility.

	#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.

	If the interface is deprecated, but still present in the interface, mark-up the
	documentation to be deprecated as well.

	#Code
	###$
	#Method void someMethodThatIsNowDeprecated()
	#Deprecated
	##
	$$

	Use

	$Code
	##Deprecated soon
	$$

	if the change is soon to be deprecated.

	$$$#

	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 ##

	#Subtopic Broken_Example

	An example may cause Bookmaker or a bot running Bookmaker to fail if it can't
	be compiled by fiddle. If the example cannot be fixed, it can be commented out
	by changing
	###$
	$Code
	$Literal
	#Example
	$Code $$
	to
	$Code
	#NoExample
	$Code $$
	$$$#
	. The disabled example can contain additional markup,
	which will be ignored.

	#Subtopic Broken_Example ##

	#Subtopic Installing

	Install
	#A Go # https://golang.org/doc/install ##
	if needed.
	Check the version. The resuls should be 1.10 or greater.

	#Code
	$ go version
	##

	Get the fiddle command line interface tool.
	By default this will appear in your home directory.

	#Code
	$ go get go.skia.org/infra/fiddlek/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 -a docs/status.json -e fiddle.json
	$ ~/go/bin/fiddlecli --input fiddle.json --output fiddleout.json
	$ ./out/skia/bookmaker -a docs/status.json -f fiddleout.json -r site/user/api -c
	$ ./out/skia/bookmaker -a docs/status.json -x
	$ ./out/skia/bookmaker -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 # https://bug.skia.org/6898 ##
	.

	##

	#Topic Bookmaker ##