refactor help.lint.coverage with complete docs and tests
Cat Stevens
John Benediktsson
parent
0763be780f
commit
e4d6ea40ca
|
|
@ -1,5 +1,5 @@
|
|||
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
|
||||
|
|
@ -18,32 +18,85 @@ $nl
|
|||
"This vocabulary is intended to be used alongside and after " { $vocab-link "help.lint" } ", not as a replacement for it."
|
||||
$nl
|
||||
"These words are provided to aid in writing more complete documentation:"
|
||||
{ $related-subsections
|
||||
word-help-coverage.
|
||||
vocab-help-coverage.
|
||||
prefix-help-coverage.
|
||||
}
|
||||
|
||||
"Coverage report objects:"
|
||||
{ $related-subsections
|
||||
word-help-coverage
|
||||
help-coverage.
|
||||
}
|
||||
|
||||
"Raw report generation:"
|
||||
{ $related-subsections
|
||||
<word-help-coverage>
|
||||
<vocab-help-coverage>
|
||||
<prefix-help-coverage>
|
||||
}
|
||||
|
||||
"Coverage reports:"
|
||||
{ $related-subsections
|
||||
word-help-coverage
|
||||
print-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"
|
||||
}
|
||||
} ;
|
||||
|
||||
|
|
@ -53,35 +106,36 @@ HELP: <prefix-help-coverage>
|
|||
{ $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 } }
|
||||
}
|
||||
{ }
|
||||
}"
|
||||
}
|
||||
} ;
|
||||
|
|
@ -106,31 +160,23 @@ HELP: <vocab-help-coverage>
|
|||
{ $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 }
|
||||
{ word-name a10n }
|
||||
{ omitted-sections { $description $examples } }
|
||||
}
|
||||
T{ word-help-coverage
|
||||
{ word-name <vocab-help-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 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 }
|
||||
{ word-name singularize }
|
||||
{ omitted-sections { $description $examples } }
|
||||
}
|
||||
}"
|
||||
}
|
||||
|
|
|
|||
|
|
@ -1,5 +1,6 @@
|
|||
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
|
||||
|
|
@ -9,7 +10,7 @@ IN: help.lint.coverage.tests
|
|||
|
||||
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
|
||||
|
|
@ -33,4 +34,35 @@ PRIVATE>
|
|||
{ { $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
|
||||
|
|
|
|||
|
|
@ -1,8 +1,9 @@
|
|||
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
|
||||
|
||||
|
|
@ -13,7 +14,7 @@ TUPLE: word-help-coverage
|
|||
{ 100%-coverage? boolean initial: f } ;
|
||||
|
||||
<PRIVATE
|
||||
! <<
|
||||
|
||||
CONSTANT: ignored-words {
|
||||
$low-level-note
|
||||
$prettyprinting-note
|
||||
|
|
@ -24,32 +25,62 @@ CONSTANT: ignored-words {
|
|||
$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 -- )
|
||||
[
|
||||
[ 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
|
||||
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 )
|
||||
[
|
||||
[ "[" ] 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
|
||||
|
||||
|
|
@ -78,30 +109,14 @@ M: word-help-coverage summary
|
|||
[ 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 ;
|
||||
|
|
@ -111,5 +126,23 @@ M: string <word-help-coverage>
|
|||
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. ;
|
||||
|
|
|
|||
Loading…
Reference in New Issue