diff options
| author |  Cary Clark <caryclark@skia.org> | 2017-08-30 08:58:10 -0400 |
|---|---|---|
| committer |  Skia Commit-Bot <skia-commit-bot@chromium.org> | 2017-08-30 13:16:12 +0000 |
| commit | a523d2d1554441a79319eb46960d7b5c2dc85d9d (patch) | |
| tree | bea460eb96b0bec9d57093d159dff0fc74f9f0d7 /docs/usingBookmaker.bmh | |
| parent | 4c6024afcce54cc775810b5f8ebccbcdbc6a43d7 (diff) | |
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 <caryclark@skia.org>
Reviewed-by: Cary Clark <caryclark@skia.org>
Diffstat (limited to 'docs/usingBookmaker.bmh')
| -rw-r--r-- | docs/usingBookmaker.bmh | 37 |
1 files changed, 36 insertions, 1 deletions
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.
|