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

1Basic Module Documentation Reflection🔗 i

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? modbinding)→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/csymbol? )
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-λ

match-λ*

match-λ**

match/derived

match/values

struct*)

procedure
( module->documented-exported-names mod)→(list/csymbol? )
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-λ

match-λ*

match-λ**

match/derived

match/values

struct*)

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

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

Example:

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

'(match-...-nesting)

2Module Documentation Statistics🔗 i

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)

32
> (module-num-exports 'racket/list)

67

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)

31

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)

31/32

3Testing Module Documentation🔗 i

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 2 undocumented bindings:

for-clause-syntax-protect

syntax-pattern-variable?

--------------------

procedure
( check-documented modbinding)→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 modratio)→void?
mod:symbol?
ratio:(and/cnumber? positive-real?)

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

Example:

> (check-documentation-ratio 'racket/match0.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.875%

--------------------

4raco doc-coverage: Documentation Coverage🔗 i

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 →