doc-coverage.scrbl (4702B)
1 #lang scribble/manual 2 3 @(require scribble/eval 4 (for-label doc-coverage 5 racket/base)) 6 7 @title{Documentation Coverage} 8 9 @(define the-eval (make-base-eval)) 10 @(the-eval '(require "main.rkt")) 11 12 @defmodule[doc-coverage] 13 14 @author[@author+email["Jack Firth" "jackhfirth@gmail.com"]] 15 16 This library provides functions for inspecting the number of 17 bindings a module exports with and without corresponding 18 Scribble documentation, as well as Rackunit tests based on 19 this information. This allows a module author to enforce in 20 a test suite that their modules provide no undocumented 21 bindings. 22 23 source code: @url["https://github.com/jackfirth/doc-coverage"] 24 25 @section{Basic Module Documentation Reflection} 26 27 These primitives for examining module documentation information 28 allow the construction of tests and reflection tools. They are 29 implemented with Racket's native module reflection functions 30 combined with Scribble's @racket[xref?] tables. 31 32 @defproc[(has-docs? [mod symbol?] [binding symbol?]) boolean?]{ 33 Returns @racket[#t] if the module @racket[mod] provides 34 @racket[binding] with documentation, and @racket[#f] 35 otherwise. 36 @examples[#:eval the-eval 37 (has-docs? 'racket/list 'second) 38 (has-docs? 'racket/match 'match-...-nesting) 39 ]} 40 41 @defproc[(module->all-exported-names [mod symbol?]) (list/c symbol?)]{ 42 Returns a list of all bindings exported by @racket[mod]. 43 Similar to @racket[module->exports], but provides no 44 phase level information and lists both value bindings 45 and syntax bindings. 46 @examples[#:eval the-eval 47 (module->all-exported-names 'racket/match) 48 ]} 49 50 @defproc[(module->documented-exported-names [mod symbol?]) (list/c symbol?)]{ 51 Returns a list of only the bindings exported by @racket[mod] 52 with Scribble documentation. 53 @examples[#:eval the-eval 54 (module->documented-exported-names 'racket/match) 55 ]} 56 57 @defproc[(module->undocumented-exported-names [mod symbol?]) (list/c symbol?)]{ 58 Returns a list of only the bindings exported by @racket[mod] 59 without Scribble documentation. 60 @examples[#:eval the-eval 61 (module->undocumented-exported-names 'racket/match) 62 ]} 63 64 @section{Module Documentation Statistics} 65 66 These procedures are simple numeric tools built on the core 67 module documentation reflection functions. 68 69 @defproc[(module-num-exports [mod symbol?]) exact-nonnegative-integer?]{ 70 Returns the number of bindings exported by @racket[mod], as 71 determined by @racket[module->all-exported-names]. 72 @examples[#:eval the-eval 73 (module-num-exports 'racket/match) 74 (module-num-exports 'racket/list) 75 ]} 76 77 @defproc[(module-num-documented-exports [mod symbol?]) exact-nonnegative-integer?]{ 78 Similar to @racket[module-num-exports], but only for documented 79 exports. 80 @examples[#:eval the-eval 81 (module-num-documented-exports 'racket/match) 82 ]} 83 84 @defproc[(module-num-undocumented-exports [mod symbol?]) exact-nonnegative-integer?]{ 85 Similar to @racket[module-num-exports], but only for undocumented 86 exports. 87 @examples[#:eval the-eval 88 (module-num-undocumented-exports 'racket/match) 89 ]} 90 91 @defproc[(module-documentation-ratio [mod symbol?]) exact-nonnegative-number?]{ 92 Returns the percentage of bindings in @racket[mod] that are 93 documented. 94 @examples[#:eval the-eval 95 (module-documentation-ratio 'racket/match) 96 ]} 97 98 @section{Testing Module Documentation} 99 100 These Rackunit checks allow flexible specification of requirements 101 of a modules documentation, including require all exports be documented, 102 only specific exports, or that a module overall document a minimum 103 percentage of its exports. 104 105 @defproc[(check-all-documented [mod symbol?]) void?]{ 106 Fails if @racket[mod] does not document all of its exports, 107 listing any undocumented exports in the failure message. 108 @examples[#:eval the-eval 109 (check-all-documented 'racket/base) 110 ]} 111 112 @defproc[(check-documented [mod symbol?] [binding symbol?]) void?]{ 113 Fails if @racket[mod] does not provide and document 114 @racket[binding]. 115 @examples[#:eval the-eval 116 (check-documented 'racket/list 'second) 117 (check-documented 'racket/match 'match-...-nesting) 118 ]} 119 120 @defproc[(check-documentation-ratio [mod symbol?] [ratio (and/c number? positive-real?)]) void?]{ 121 Fails if @racket[mod] does not document at least @racket[ratio] 122 of its provided bindings. 123 @examples[#:eval the-eval 124 (check-documentation-ratio 'racket/match .99) 125 ]} 126 127 @section{@tt{raco doc-coverage}: Documentation Coverage} 128 129 The @tt{raco doc-coverage} command checks the documentation coverage in 130 specific modules. 131 132 Command-line flags: 133 @itemlist[ 134 @item{@Flag{h} or @DFlag{help} --- show help information for this command} 135 @item{@DFlag{} --- do not treat any remaining arguments as switches} 136 ]