diff --git a/scribblings/api.scrbl b/scribblings/api.scrbl index e06548f..b8bdfa1 100644 --- a/scribblings/api.scrbl +++ b/scribblings/api.scrbl @@ -5,16 +5,33 @@ @defmodule[cover #:use-sources (cover)] -In addition to a raco tool Cover provides racket bindings for running +In addition to being a raco tool, Cover provides racket bindings for running tests and collecting coverage information. The following are the basic functions of test coverage. +@deftogether[(@defthing[coverage/c + contract? + #:value (hash/c (and/c path-string? absolute-path?) + file-coverage/c)] + @defthing[file-coverage/c contract? #:value (listof (list/c boolean? srcloc?))])]{ +Coverage information is a hash map mapping absolute +file paths to a list detailing the coverage of that file. The file coverage +information is a list of lists, mapping a boolean to a range of +characters within the file. True means the @racket[srcloc] structure +represents an expression that was run, and False means the structure +represents an expression that was not run. Some expressions may not be +represented directly in this coverage information. +For example, type annotations in @racketmodname[typed/racket] +removed during macro expansion and are thus neither run or not run. +Note that the @racket[srcloc]s are one indexed, meaning a @racket[1] +represents the first character in the file.} + @defproc[(test-files! (#:submod submod symbol? 'test) (files path-string?) ...) any]{ -Runs all given @racket[files] and there submodule @racket[submod] (if it exists), -storing the coverage information. Returns false if tests failed. Test coverage -information is still collected when test fail. Test coverage info is added to -existing coverage info.} +Runs all given @racket[files] and their submodule @racket[submod] (if it exists), storing the coverage information. +The function returns false if any tests fail. +Test coverage information is still collected when test fail. +Test coverage info is added to existing coverage info.} @defproc[(clear-coverage!) any]{Clears all coverage information.} @@ -30,8 +47,8 @@ a functions that determines if some @racket[1] indexed character or byte locatio in that file is covered. By default it checks character locations. There are three possible results: -@itemize[@item{@racket['missing] --- The location is not in the -coverage information, is in a submodule, or lexes (in the sense of that languages +@itemize[@item{@racket['missing] --- The location is not considered relevant to coverage information. +It might be in a submodule or lexes (in the sense of that languages @racket[_color-lexer]) as a comment or whitespace.} @item{@racket['yes] --- The location is not @racket['missing] and is covered} @item{@racket['no] --- The location is not @racket['missing] @@ -43,20 +60,3 @@ and is not covered}] Generates coverage information in the coveralls and html formats. Equivalent to the specifications of the @Flag{c} argument to @exec{raco cover}.} - -@deftogether[(@defthing[coverage/c - contract? - #:value (hash/c (and/c path-string? absolute-path?) - file-coverage/c)] - @defthing[file-coverage/c contract? #:value (listof (list/c boolean? srcloc?))])]{ -Coverage information is a hash map mapping absolute -file paths to a list detailing the coverage of that file. The coverage -information is a list of lists, mapping a boolean to a range of -characters within the file. True means the @racket[srcloc] structure -represents an expression that was run, and False means the structure -represents an expression that was not run. Not that not all -expressions may be represented directly in this coverage -information. For example, type annotations in @racket[typed/racket] -removed during macro expansion and are thus neither run or not run. -Not that the @racket[srcloc]s are one indexed, meaning a @racket[1] -represents the first character in the file.} diff --git a/scribblings/basics.scrbl b/scribblings/basics.scrbl index 8ca25dc..fd7fb22 100644 --- a/scribblings/basics.scrbl +++ b/scribblings/basics.scrbl @@ -24,10 +24,10 @@ The @exec{raco cover} command accepts the following flags: output file.}]} @item{@Flag{d} or @DFlag{directory} - --- Specifies the directory output the coverage too. + --- Specifies the directory to output coverage information to. defaults to @filepath{coverage}.} @item{@Flag{e} or @DFlag{exclude-from-output} - --- excludes any directories by given name from the coverage report. + --- excludes any directories by name from the coverage report. Files in these directories are still run, they are just excluded from the outputted coverage. This flag may appear any number of times.} @item{@Flag{p} or @DFlag{exclude-pkg-defaults} diff --git a/scribblings/cover.scrbl b/scribblings/cover.scrbl index 808b2a5..39874f7 100644 --- a/scribblings/cover.scrbl +++ b/scribblings/cover.scrbl @@ -5,7 +5,7 @@ @author[(author+email "Spencer Florence" "spencer@florence.io") (author+email "Ryan Plessner" "rpless@ccs.neu.edu")] -Cover is a test coverage tool. It is designed to be used in addition to raco test +Cover is a test coverage tool. It is designed to be used in addition to raco test. @table-of-contents[] diff --git a/scribblings/plugins.scrbl b/scribblings/plugins.scrbl index e9fe4d2..e553d05 100644 --- a/scribblings/plugins.scrbl +++ b/scribblings/plugins.scrbl @@ -12,7 +12,7 @@ put a definition for @racket[cover-formats] into a packages @filepath["info.rkt" use this format.} @item{@racket[_module-path] should be the path to a racket file providing this format.} @item{@@racket[_function-name] should be a symbol that is - bound to a function in @racket[_module-math]. It should match the contract + bound to a function in @racket[_module-path]. It should match the contract @racket[(->* (coverage/c) (path-string?) any)], and is the implementation of the format.} }