Documentation Coverage
1 Basic Module Documentation Reflection
has-docs?
module->all-exported-names
module->documented-exported-names
module->undocumented-exported-names
2 Module Documentation Statistics
module-num-exports
module-num-documented-exports
module-num-undocumented-exports
module-documentation-ratio
3 Testing Module Documentation
check-all-documented
check-documented
check-documentation-ratio
4 raco doc-coverage:   Documentation Coverage
7.1

Documentation Coverage

Jack Firth <[email protected]>

 (require doc-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)

'(exn:misc:match?

  match-equality-test

  legacy-match-expander?

  match-...-nesting

  match-expander?

  prop:legacy-match-expander

  prop:match-expander

  syntax-local-match-introduce

  ==

  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)

'(exn:misc:match?

  match-equality-test

  legacy-match-expander?

  match-expander?

  prop:legacy-match-expander

  prop:match-expander

  syntax-local-match-introduce

  ==

  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)

61

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

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

28

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

Example:

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

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

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

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