extra/help/lint/coverage/coverage-docs.factor

   1 USING: help help.lint.coverage help.lint.coverage.private
   2 help.markup help.syntax io kernel sequences strings vocabs words ;
   3 IN: help.lint.coverage
   4
   5 <PRIVATE
   6 : $related-subsections ( element -- )
   7     [ related-words ] [ $subsections ] bi ;
   8 PRIVATE>
   9
  10 ABOUT: "help.lint.coverage"
  11
  12 ARTICLE: "help.lint.coverage" "Help coverage linting"
  13 "The " { $vocab-link "help.lint.coverage" } " vocabulary implements a very pedantic documentation completeness checker."
  14 $nl
  15 "The documentation coverage linter requires most words to have " { $link POSTPONE: HELP: } " declarations defining some of the "
  16 { $links $values $description $error-description $class-description $examples } " sections (see " { $links "element-types" } ")."
  17 $nl
  18 "This vocabulary is intended to be used alongside and after " { $vocab-link "help.lint" } ", not as a replacement for it."
  19 $nl
  20 "These words are provided to aid in writing more complete documentation:"
  21 { $related-subsections
  22     word-help-coverage.
  23     vocab-help-coverage.
  24     prefix-help-coverage.
  25 }
  26
  27 "Coverage report objects:"
  28 { $related-subsections
  29     word-help-coverage
  30     help-coverage.
  31 }
  32
  33 "Raw report generation:"
  34 { $related-subsections
  35     <word-help-coverage>
  36     <vocab-help-coverage>
  37     <prefix-help-coverage>
  38 } ;
  39
  40 { word-help-coverage word-help-coverage. <word-help-coverage> <vocab-help-coverage> <prefix-help-coverage> }
  41 related-words
  42
  43 HELP: word-help-coverage
  44 { $class-description "A documentation coverage report for a single word." } ;
  45
  46 HELP: help-coverage.
  47 { $values { "coverage" word-help-coverage } }
  48 { $contract "Displays a coverage object." }
  49 { $examples
  50     { $example
  51         "USING: help.lint.coverage ;"
  52         "\\ <word-help-coverage> <word-help-coverage> help-coverage."
  53         "[help.lint.coverage] <word-help-coverage>: full help coverage"
  54     }
  55 } ;
  56
  57 HELP: word-help-coverage.
  58 { $values { "word-spec" { $or word string } } }
  59 { $description "Prettyprints a help coverage report of " { $snippet "word-spec" } " to " { $link output-stream } "." }
  60 { $examples
  61     { $example
  62         "USING: sequences help.lint.coverage ;"
  63         "\\ map word-help-coverage."
  64         "[sequences] map: needs help section: $examples"
  65     }
  66 } ;
  67
  68 HELP: vocab-help-coverage.
  69 { $values { "vocab-spec" { $or vocab string } } }
  70 { $description "Prettyprints a help coverage report of " { $snippet "vocab-spec" } " to " { $link output-stream } "." }
  71 { $examples
  72     { $example
  73         "USING: help.lint.coverage ;"
  74         "\"english\" vocab-help-coverage."
  75 "[english] $or-markup-example: full help coverage
  76 [english] ?plural-article: full help coverage
  77 [english] ?pluralize: full help coverage
  78 [english] a/an: full help coverage
  79 [english] a10n: full help coverage
  80 [english] comma-list: full help coverage
  81 [english] count-of-things: full help coverage
  82 [english] or-markup-example: full help coverage
  83 [english] plural?: full help coverage
  84 [english] pluralize: full help coverage
  85 [english] singular?: full help coverage
  86 [english] singularize: full help coverage
  87
  88 100.0% of words have complete documentation"
  89     }
  90 } ;
  91
  92 HELP: prefix-help-coverage.
  93 { $values { "prefix-spec" { $or vocab string } } { "private?" boolean } }
  94 { $description "Prettyprints a help coverage report of " { $snippet "prefix-spec" } " to " { $link output-stream } "." }
  95 { $examples
  96     { $example
  97         "USING: help.lint.coverage ;"
  98         "\"english\" t prefix-help-coverage."
  99 "[english] $or-markup-example: full help coverage
 100 [english] ?plural-article: full help coverage
 101 [english] ?pluralize: full help coverage
 102 [english] a/an: full help coverage
 103 [english] a10n: full help coverage
 104 [english] comma-list: full help coverage
 105 [english] count-of-things: full help coverage
 106 [english] or-markup-example: full help coverage
 107 [english] plural?: full help coverage
 108 [english] pluralize: full help coverage
 109 [english] singular?: full help coverage
 110 [english] singularize: full help coverage
 111 [english.private] $0-plurality: needs help sections: $values, $description, and $examples
 112 [english.private] $keep-case: needs help sections: $values, $description, and $examples
 113 [english.private] match-case: needs help sections: $values, $description, and $examples
 114 [english.private] plural-to-singular: needs help sections: $values, $description, and $examples
 115 [english.private] singular-to-plural: needs help sections: $values, $description, and $examples
 116
 117 70.6% of words have complete documentation"
 118     }
 119 } ;
 120
 121 HELP: <prefix-help-coverage>
 122 { $values { "prefix" string } { "private?" boolean } { "coverage" sequence } }
 123 { $description "Runs the help coverage checker on every child vocabulary of the given " { $snippet "prefix" } ", including the base vocabulary. If " { $snippet "private?" } " is " { $snippet "f" } ", the prefix's child " { $snippet ".private" } " vocabularies are not checked. If " { $snippet "private?" } " is " { $snippet "t" } ", " { $emphasis "all" } " child vocabularies are checked." }
 124 { $examples
 125     { $example
 126         "USING: help.lint.coverage prettyprint ;"
 127         "\"english\" t <prefix-help-coverage> ..."
 128 "{
 129     T{ word-help-coverage
 130         { word-name $or-markup-example }
 131         { 100%-coverage? t }
 132     }
 133     T{ word-help-coverage
 134         { word-name ?plural-article }
 135         { 100%-coverage? t }
 136     }
 137     T{ word-help-coverage
 138         { word-name ?pluralize }
 139         { 100%-coverage? t }
 140     }
 141     T{ word-help-coverage
 142         { word-name a/an }
 143         { 100%-coverage? t }
 144     }
 145     T{ word-help-coverage
 146         { word-name a10n }
 147         { 100%-coverage? t }
 148     }
 149     T{ word-help-coverage
 150         { word-name comma-list }
 151         { 100%-coverage? t }
 152     }
 153     T{ word-help-coverage
 154         { word-name count-of-things }
 155         { 100%-coverage? t }
 156     }
 157     T{ word-help-coverage
 158         { word-name or-markup-example }
 159         { 100%-coverage? t }
 160     }
 161     T{ word-help-coverage
 162         { word-name plural? }
 163         { 100%-coverage? t }
 164     }
 165     T{ word-help-coverage
 166         { word-name pluralize }
 167         { 100%-coverage? t }
 168     }
 169     T{ word-help-coverage
 170         { word-name singular? }
 171         { 100%-coverage? t }
 172     }
 173     T{ word-help-coverage
 174         { word-name singularize }
 175         { 100%-coverage? t }
 176     }
 177     T{ word-help-coverage
 178         { word-name $0-plurality }
 179         { omitted-sections { $values $description $examples } }
 180     }
 181     T{ word-help-coverage
 182         { word-name $keep-case }
 183         { omitted-sections { $values $description $examples } }
 184     }
 185     T{ word-help-coverage
 186         { word-name match-case }
 187         { omitted-sections { $values $description $examples } }
 188     }
 189     T{ word-help-coverage
 190         { word-name plural-to-singular }
 191         { omitted-sections { $values $description $examples } }
 192     }
 193     T{ word-help-coverage
 194         { word-name singular-to-plural }
 195         { omitted-sections { $values $description $examples } }
 196     }
 197 }"
 198     }
 199 } ;
 200
 201 HELP: <word-help-coverage>
 202 { $values { "word" { $or string word } } { "coverage" word-help-coverage } }
 203 { $contract "Looks up a word in the current scope and generates a documentation coverage report for it." }
 204 { $examples
 205     { $example
 206         "USING: help.lint.coverage prettyprint ;"
 207         "\\ <word-help-coverage> <word-help-coverage> ..."
 208 "T{ word-help-coverage
 209     { word-name <word-help-coverage> }
 210     { 100%-coverage? t }
 211 }"
 212     }
 213 } ;
 214
 215 HELP: <vocab-help-coverage>
 216 { $values { "vocab-spec" { $or vocab string } } { "coverage" sequence } }
 217 { $description "Runs the help coverage checker on the vocabulary in the given " { $snippet "vocab-spec" } "." }
 218 { $examples
 219     { $example
 220         "USING: help.lint.coverage prettyprint ;"
 221         "\"english\" <vocab-help-coverage> ..."
 222 "{
 223     T{ word-help-coverage
 224         { word-name $or-markup-example }
 225         { 100%-coverage? t }
 226     }
 227     T{ word-help-coverage
 228         { word-name ?plural-article }
 229         { 100%-coverage? t }
 230     }
 231     T{ word-help-coverage
 232         { word-name ?pluralize }
 233         { 100%-coverage? t }
 234     }
 235     T{ word-help-coverage
 236         { word-name a/an }
 237         { 100%-coverage? t }
 238     }
 239     T{ word-help-coverage
 240         { word-name a10n }
 241         { 100%-coverage? t }
 242     }
 243     T{ word-help-coverage
 244         { word-name comma-list }
 245         { 100%-coverage? t }
 246     }
 247     T{ word-help-coverage
 248         { word-name count-of-things }
 249         { 100%-coverage? t }
 250     }
 251     T{ word-help-coverage
 252         { word-name or-markup-example }
 253         { 100%-coverage? t }
 254     }
 255     T{ word-help-coverage
 256         { word-name plural? }
 257         { 100%-coverage? t }
 258     }
 259     T{ word-help-coverage
 260         { word-name pluralize }
 261         { 100%-coverage? t }
 262     }
 263     T{ word-help-coverage
 264         { word-name singular? }
 265         { 100%-coverage? t }
 266     }
 267     T{ word-help-coverage
 268         { word-name singularize }
 269         { 100%-coverage? t }
 270     }
 271 }"
 272     }
 273 } ;