-USING: help help.lint.coverage help.lint.coverage.private help.markup help.syntax kernel
-sequences strings vocabs words ;
+USING: help help.lint.coverage help.lint.coverage.private
+help.markup help.syntax io kernel sequences strings vocabs words ;
IN: help.lint.coverage
<PRIVATE
$nl
"These words are provided to aid in writing more complete documentation:"
{ $related-subsections
- <word-help-coverage>
- <vocab-help-coverage>
- <prefix-help-coverage>
+ word-help-coverage.
+ vocab-help-coverage.
+ prefix-help-coverage.
}
-"Coverage reports:"
+"Coverage report objects:"
{ $related-subsections
word-help-coverage
- print-coverage
+ help-coverage.
+}
+
+"Raw report generation:"
+{ $related-subsections
+ <word-help-coverage>
+ <vocab-help-coverage>
+ <prefix-help-coverage>
} ;
-{ <word-help-coverage> <vocab-help-coverage> <prefix-help-coverage> word-help-coverage }
+{ word-help-coverage word-help-coverage. <word-help-coverage> <vocab-help-coverage> <prefix-help-coverage> }
related-words
HELP: word-help-coverage
{ $class-description "A documentation coverage report for a single word." } ;
-HELP: print-coverage
+HELP: help-coverage.
{ $values { "coverage" word-help-coverage } }
{ $contract "Displays a coverage object." }
{ $examples
{ $example
- "USING: help.lint.coverage io ;"
- "\\ <word-help-coverage> <word-help-coverage> print-coverage"
- "Word '<word-help-coverage>' has 100% help coverage"
+ "USING: help.lint.coverage ;"
+ "\\ <word-help-coverage> <word-help-coverage> help-coverage."
+ "[help.lint.coverage] <word-help-coverage>: full help coverage"
+ }
+} ;
+
+HELP: word-help-coverage.
+{ $values { "word-spec" { $or word string } } }
+{ $description "Prettyprints a help coverage report of " { $snippet "word-spec" } " to " { $link output-stream } "." }
+{ $examples
+ { $example
+ "USING: sequences help.lint.coverage ;"
+ "\\ map word-help-coverage."
+ "[sequences] map: needs help section: $examples"
+ }
+} ;
+
+HELP: vocab-help-coverage.
+{ $values { "vocab-spec" { $or vocab string } } }
+{ $description "Prettyprints a help coverage report of " { $snippet "vocab-spec" } " to " { $link output-stream } "." }
+{ $examples
+ { $example
+ "USING: help.lint.coverage ;"
+ "\"english\" vocab-help-coverage."
+"[english] a10n: needs help sections: $description $examples
+[english] count-of-things: needs help sections: $description $examples
+[english] pluralize: needs help sections: $description $examples
+[english] singularize: needs help sections: $description $examples
+
+0.0% of words have complete documentation"
+ }
+} ;
+
+HELP: prefix-help-coverage.
+{ $values { "prefix-spec" { $or vocab string } } { "private?" boolean } }
+{ $description "Prettyprints a help coverage report of " { $snippet "prefix-spec" } " to " { $link output-stream } "." }
+{ $examples
+ { $example
+ "USING: help.lint.coverage ;"
+ "\"english\" t prefix-help-coverage."
+"[english] a10n: needs help sections: $description $examples
+[english] count-of-things: needs help sections: $description $examples
+[english] pluralize: needs help sections: $description $examples
+[english] singularize: needs help sections: $description $examples
+[english.private] match-case: needs help sections: $description $examples
+[english.private] plural-to-singular: needs help sections: $description $examples
+[english.private] singular-to-plural: needs help sections: $description $examples
+
+0.0% of words have complete documentation"
}
} ;
{ $examples
{ $example
"USING: help.lint.coverage prettyprint ;"
- "\"help.lint.coverage\" f <prefix-help-coverage> ."
+ "\"english\" t <prefix-help-coverage> ."
"{
- {
- T{ word-help-coverage
- { word-name <prefix-help-coverage> }
- { 100%-coverage? t }
- }
- T{ word-help-coverage
- { word-name <vocab-help-coverage> }
- { 100%-coverage? t }
- }
- T{ word-help-coverage
- { word-name <word-help-coverage> }
- { 100%-coverage? t }
- }
- T{ word-help-coverage
- { word-name print-coverage }
- { 100%-coverage? t }
- }
- T{ word-help-coverage
- { word-name word-help-coverage }
- { 100%-coverage? t }
- }
- T{ word-help-coverage
- { word-name word-help-coverage? }
- { 100%-coverage? t }
- }
- }
- { }
+ T{ word-help-coverage
+ { word-name a10n }
+ { omitted-sections { $description $examples } }
+ }
+ T{ word-help-coverage
+ { word-name count-of-things }
+ { omitted-sections { $description $examples } }
+ }
+ T{ word-help-coverage
+ { word-name pluralize }
+ { omitted-sections { $description $examples } }
+ }
+ T{ word-help-coverage
+ { word-name singularize }
+ { omitted-sections { $description $examples } }
+ }
+ T{ word-help-coverage
+ { word-name match-case }
+ { omitted-sections { $description $examples } }
+ }
+ T{ word-help-coverage
+ { word-name plural-to-singular }
+ { omitted-sections { $description $examples } }
+ }
+ T{ word-help-coverage
+ { word-name singular-to-plural }
+ { omitted-sections { $description $examples } }
+ }
}"
}
} ;
{ $examples
{ $example
"USING: help.lint.coverage prettyprint ;"
- "\"help.lint.coverage\" <vocab-help-coverage> ."
+ "\"english\" <vocab-help-coverage> ."
"{
T{ word-help-coverage
- { word-name <prefix-help-coverage> }
- { 100%-coverage? t }
- }
- T{ word-help-coverage
- { word-name <vocab-help-coverage> }
- { 100%-coverage? t }
- }
- T{ word-help-coverage
- { word-name <word-help-coverage> }
- { 100%-coverage? t }
+ { word-name a10n }
+ { omitted-sections { $description $examples } }
}
T{ word-help-coverage
- { word-name print-coverage }
- { 100%-coverage? t }
+ { word-name count-of-things }
+ { omitted-sections { $description $examples } }
}
T{ word-help-coverage
- { word-name word-help-coverage }
- { 100%-coverage? t }
+ { word-name pluralize }
+ { omitted-sections { $description $examples } }
}
T{ word-help-coverage
- { word-name word-help-coverage? }
- { 100%-coverage? t }
+ { word-name singularize }
+ { omitted-sections { $description $examples } }
}
}"
}
-USING: help.lint.coverage help.lint.coverage.private help.markup
-help.syntax kernel math.matrices sorting tools.test vocabs ;
+USING: accessors fuel.help.private help.lint.coverage
+help.lint.coverage.private help.markup help.syntax kernel
+literals math math.matrices sorting tools.test vocabs ;
IN: help.lint.coverage.tests
<PRIVATE
HELP: empty { $examples } ;
HELP: nonexistent ;
-HELP: defined { $examples { $example "USING: x ;" "blah" "hahaha" } } ;
+HELP: defined { $examples { $example "USING: prettyprint ; ""1 ." "1" } } ;
PRIVATE>
{ t } [ \ empty empty-examples? ] unit-test
{ { $values $description $examples } } [ \ keep word-defines-sections ] unit-test
{ { $values $contract $examples } } [ \ <word-help-coverage> word-defines-sections ] unit-test
-{ eye } [ "eye" loaded-vocab-names resolve-name-in ] unit-test
+{ eye } [ "eye" find-word ] unit-test
+
+{
+ V{ "[" { $[ "math" dup lookup-vocab ] } "] " { "zero?" zero? } ": " }
+} [
+ V{ } clone \ zero? (assemble-word-metadata)
+] unit-test
+{
+ V{ "empty " { "$examples" $examples } "; " }
+} [
+ V{ } clone word-help-coverage new t >>empty-examples? (assemble-empty-examples)
+] unit-test
+
+{
+ V{ "needs help " "sections: " { { "$description" $description } { "$examples" $examples } } }
+} [
+ V{ } clone word-help-coverage new { $description $examples } >>omitted-sections (assemble-omitted-sections)
+] unit-test
+{
+ V{ "needs help " "section: " { { "$description" $description } } }
+} [
+ V{ } clone word-help-coverage new { $description } >>omitted-sections (assemble-omitted-sections)
+] unit-test
+{
+ V{ "full help coverage" }
+} [
+ V{ } clone word-help-coverage new t >>100%-coverage? (assemble-full-coverage)
+] unit-test
+
+! make sure this doesn't throw an error (would signify an issue with ignored-words)
+! the contents of all-words is not important
+{ } [ all-words [ <word-help-coverage> ] map drop ] unit-test
USING: accessors arrays classes classes.error combinators
combinators.short-circuit continuations english eval formatting
-fry generic help help.lint help.lint.checks help.markup io
-kernel math namespaces parser prettyprint sequences sets sorting
-splitting strings summary vocabs words ;
+fry fuel.help.private generic help help.lint help.lint.checks help.markup io
+io.streams.string io.styles kernel math namespaces parser
+prettyprint sequences sequences.deep sets sorting splitting strings summary
+vocabs words ;
FROM: namespaces => set ;
IN: help.lint.coverage
{ 100%-coverage? boolean initial: f } ;
<PRIVATE
-! <<
+
CONSTANT: ignored-words {
$low-level-note
$prettyprinting-note
$complex-shuffle
$nl
}
-! >>
DEFER: ?pluralize
-M: word-help-coverage summary
- [ word-name>> [ vocabulary>> ] [ name>> ] bi "[%s] %s: " sprintf ] keep
- dup 100%-coverage?>>
- [ drop "full help coverage" append ]
+: write-object-seq ( object-seq -- )
+ [
+ dup array? [
+ dup ?first array?
+ [ dup length '[
+ swap first2 write-object
+ _ 1 - abs = not [ " " write ] when
+ ] each-index
+ ] [ first2 write-object ] if
+ ] [ write ] if
+ ] each ; inline
+
+: (assemble-word-metadata) ( vec word -- vec )
[
- [ empty-examples?>> "defined empty { $examples }, " "" ? ]
- [ omitted-sections>> dup [
- length "section" ?pluralize
- ] dip
- [ name>> ] map ", " join
- ] bi
- "%sshould define help %s %s" sprintf append
- ] if ; inline
+ [ "[" ] dip vocabulary>> dup lookup-vocab 2array "] "
+ 3array over push-all
+ ] [
+ [ name>> ] keep 2array ": "
+ 2array over push-all
+ ] bi ; inline
+
+: (assemble-empty-examples) ( vec coverage -- vec )
+ empty-examples?>> [ "empty " \ $examples [ name>> ] keep 2array "; "
+ 3array over push-all
+ ] when ;
+
+: (assemble-omitted-sections) ( vec coverage -- vec )
+ omitted-sections>> [
+ length "section" ?pluralize ": " append
+ ] [
+ [ [ name>> ] keep 2array ] map
+ ] bi
+ [ "needs help " ] 2dip
+ 3array over push-all ;
+
+: (assemble-full-coverage) ( vec coverage -- vec )
+ drop "full help coverage" over push ;
+
+: (present-coverage) ( coverage-report -- )
+ [ V{ } clone ] dip
+ [ word-name>> (assemble-word-metadata) ] keep
+ dup 100%-coverage?>>
+ [ (assemble-full-coverage) ] [
+ [ (assemble-empty-examples) ]
+ [ (assemble-omitted-sections) ] bi
+ ] if "\n" over push write-object-seq ;
+
+M: word-help-coverage summary
+ [ (present-coverage) ] with-string-writer ; inline
: sorted-loaded-child-vocabs ( prefix -- assoc )
loaded-child-vocab-names natural-sort ; inline
-: resolve-name-in ( name namespaces -- word )
- "syntax" swap remove " " join
- "USING: " " ; \\ " surround
- prepend eval( -- word ) ;
-
: filter-private ( seq -- no-private )
[ ".private" ?tail nip not ] filter ; inline
[ should-define ] [ word-defines-sections ] bi diff ;
PRIVATE>
-GENERIC: print-coverage ( coverage-seq -- )
-M: sequence print-coverage
- [
- [ print-coverage ] each
- ] [
- [ [ 100%-coverage?>> ] count ] [ length ] bi /f
- 100 *
- "\n%3.1f%% of words have complete documentation\n"
- printf
- ] bi ;
-
-M: word-help-coverage print-coverage
- summary print ;
-
GENERIC: <word-help-coverage> ( word -- coverage )
M: word <word-help-coverage>
- dup
- [ missing-sections ]
- [ empty-examples? ] bi
+ dup [ missing-sections ] [ empty-examples? ] bi
2dup 2array { { } f } =
word-help-coverage boa ; inline
M: string <word-help-coverage>
- loaded-vocab-names resolve-name-in <word-help-coverage> ; inline
+ find-word <word-help-coverage> ; inline
: <vocab-help-coverage> ( vocab-spec -- coverage )
[ auto-use? off vocab-words natural-sort [ <word-help-coverage> ] map ] with-scope ;
auto-use? off group-articles vocab-articles set
[ sorted-loaded-child-vocabs ] dip not
[ filter-private ] when
- [ <vocab-help-coverage> ] map
+ [ <vocab-help-coverage> ] map flatten
] with-scope ;
+
+GENERIC: help-coverage. ( coverage -- )
+M: sequence help-coverage.
+ [
+ [ help-coverage. ] each
+ ] [
+ [ [ 100%-coverage?>> ] count ] [ length ] bi /f
+ 100 *
+ "\n%3.1f%% of words have complete documentation\n"
+ printf
+ ] bi ; recursive
+
+M: word-help-coverage help-coverage.
+ (present-coverage) ;
+
+: word-help-coverage. ( word-spec -- ) <word-help-coverage> help-coverage. ;
+: vocab-help-coverage. ( vocab-spec -- ) <vocab-help-coverage> help-coverage. ;
+: prefix-help-coverage. ( prefix-spec private? -- ) <prefix-help-coverage> help-coverage. ;