Documentation Coverage

6.3.90.900

top ← prev up next →

Documentation Coverage

package: doc-coverage

This library provides functions for inspecting the number of bindings a module exports with and without corresponding Scribble documentation, as well as Rackunit tests based on this information. This allows a module author to enforce in a test suite that their modules provide no undocumented bindings.

source code: https://github.com/jackfirth/doc-coverage

1 Basic Module Documentation Reflection

These primitives for examining module documentation information allow the construction of tests and reflection tools. They are implemented with Racket’s native module reflection functions combined with Scribble’s xref? tables.

procedure
(has-docs? mod binding) → boolean?
mod : symbol?
binding : symbol?

Returns #t if the module mod provides binding with documentation, and #f otherwise.

Examples:

> (has-docs? 'racket/list 'second)
#t
> (has-docs? 'racket/match 'match-...-nesting)
#f

procedure
(module->all-exported-names mod) → (list/c symbol?)
mod : symbol?

Returns a list of all bindings exported by mod. Similar to module->exports, but provides no phase level information and lists both value bindings and syntax bindings.

Example:

> (module->all-exported-names 'racket/match)
'(legacy-match-expander?
  match-...-nesting
  match-expander?
  prop:legacy-match-expander
  prop:match-expander
  syntax-local-match-introduce
  exn:misc:match?
  match-equality-test
  ==
  define-match-expander
  define/match
  failure-cont
  match
  match*
  match*/derived
  match-define
  match-define-values
  match-lambda
  match-lambda*
  match-lambda**
  match-let
  match-let*
  match-let*-values
  match-let-values
  match-letrec
  match-letrec-values
  match/derived
  match/values
  struct*)

procedure
(module->documented-exported-names mod) → (list/c symbol?)
mod : symbol?

Returns a list of only the bindings exported by mod with Scribble documentation.

Example:

> (module->documented-exported-names 'racket/match)
'(legacy-match-expander?
  match-expander?
  prop:legacy-match-expander
  prop:match-expander
  syntax-local-match-introduce
  exn:misc:match?
  match-equality-test
  ==
  define-match-expander
  define/match
  failure-cont
  match
  match*
  match*/derived
  match-define
  match-define-values
  match-lambda
  match-lambda*
  match-lambda**
  match-let
  match-let*
  match-let*-values
  match-let-values
  match-letrec
  match-letrec-values
  match/derived
  match/values
  struct*)

procedure
(module->undocumented-exported-names mod) → (list/c symbol?)
mod : symbol?

Returns a list of only the bindings exported by mod without Scribble documentation.

Example:

> (module->undocumented-exported-names 'racket/match)
'(match-...-nesting)

2 Module Documentation Statistics

These procedures are simple numeric tools built on the core module documentation reflection functions.

procedure
(module-num-exports mod) → exact-nonnegative-integer?
mod : symbol?

Returns the number of bindings exported by mod, as determined by module->all-exported-names.

Examples:

> (module-num-exports 'racket/match)
29
> (module-num-exports 'racket/list)
57

procedure
(module-num-documented-exports mod)
→ exact-nonnegative-integer?
mod : symbol?

Similar to module-num-exports, but only for documented exports.

Example:

> (module-num-documented-exports 'racket/match)
28

procedure
(module-num-undocumented-exports mod)
→ exact-nonnegative-integer?
mod : symbol?

Similar to module-num-exports, but only for undocumented exports.

Example:

> (module-num-undocumented-exports 'racket/match)
1

procedure
(module-documentation-ratio mod) → exact-nonnegative-number?
mod : symbol?

Returns the percentage of bindings in mod that are documented.

Example:

> (module-documentation-ratio 'racket/match)
28/29

3 Testing Module Documentation

These Rackunit checks allow flexible specification of requirements of a modules documentation, including require all exports be documented, only specific exports, or that a module overall document a minimum percentage of its exports.

procedure
(check-all-documented mod) → void?
mod : symbol?

Fails if mod does not document all of its exports, listing any undocumented exports in the failure message.

Example:

> (check-all-documented 'racket/base)
--------------------
FAILURE
name:       check-all-documented
location:   (eval 12 0 12 1)
expression: (check-all-documented (quote racket/base))
params:     (racket/base)
Module racket/base has 3 undocumented bindings:
expand-for-clause
for-clause-syntax-protect
syntax-pattern-variable?
--------------------

procedure
(check-documented mod binding) → void?
mod : symbol?
binding : symbol?

Fails if mod does not provide and document binding.

Examples:

> (check-documented 'racket/list 'second)
> (check-documented 'racket/match 'match-...-nesting)
--------------------
FAILURE
name:       check-documented
location:   (eval 14 0 14 1)
expression: (check-documented (quote racket/match) (quote match-...-nesting))
params:     (racket/match match-...-nesting)
Module racket/match does not document binding match-...-nesting
--------------------

procedure
(check-documentation-ratio mod ratio) → void?
mod : symbol?
ratio : (and/c number? positive-real?)

Fails if mod does not document at least ratio of its provided bindings.

Example:

> (check-documentation-ratio 'racket/match 0.99)
--------------------
FAILURE
name:       check-documentation-ratio
location:   (eval 15 0 15 1)
expression: (check-documentation-ratio (quote racket/match) 0.99)
params:     (racket/match 0.99)
Module racket/match does not document at least 99.0% of its bindings, only documents 96.55172413793103%
--------------------

4 raco doc-coverage: Documentation Coverage

The raco doc-coverage command checks the documentation coverage in specific modules.

Command-line flags:

-h or --help — show help information for this command
-- — do not treat any remaining arguments as switches

top ← prev up next →

1	Basic Module Documentation Reflection
2	Module Documentation Statistics
3	Testing Module Documentation
4	raco doc-coverage: Documentation Coverage