From a523d2d1554441a79319eb46960d7b5c2dc85d9d Mon Sep 17 00:00:00 2001 From: Cary Clark Date: Wed, 30 Aug 2017 08:58:10 -0400 Subject: fix param return descriptions enforce that param and return descriptions are phrases (begin with lower case, no trailing period). Docs-Preview: https://skia.org/?cl=40767 Bug: skia: 6898 Change-Id: Ib5f2a02441673f71c0780d81c5e4c61200a678e3 Reviewed-on: https://skia-review.googlesource.com/40767 Commit-Queue: Cary Clark Reviewed-by: Cary Clark --- docs/usingBookmaker.bmh | 37 ++++++++++++++++++++++++++++++++++++- 1 file changed, 36 insertions(+), 1 deletion(-) (limited to 'docs/usingBookmaker.bmh') diff --git a/docs/usingBookmaker.bmh b/docs/usingBookmaker.bmh index 5a088b3d02..60505ca279 100644 --- a/docs/usingBookmaker.bmh +++ b/docs/usingBookmaker.bmh @@ -2,7 +2,7 @@ SkXXX bmh_SkXXX CL -C +Go Visual_Studio ## @@ -10,7 +10,9 @@ Visual_Studio How to use the Bookmaker utility. +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 @@ -33,6 +35,39 @@ $ ./out/dir/bookmaker -t -i include/core/SkXXX.h Copy SkXXX.bmh to docs. Use your favorite editor to fill out docs/SkXXX.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. + +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 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. + +## + 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. -- cgit v1.2.3