diff --git a/extra/help/lint/coverage/coverage-docs.factor b/extra/help/lint/coverage/coverage-docs.factor index 1191b1f1df..c591786629 100644 --- a/extra/help/lint/coverage/coverage-docs.factor +++ b/extra/help/lint/coverage/coverage-docs.factor @@ -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 -} - -"Coverage reports:" -{ $related-subsections - word-help-coverage - print-coverage } ; -{ word-help-coverage } +{ word-help-coverage word-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 ;" - "\\ print-coverage" - "Word '' has 100% help coverage" + "USING: help.lint.coverage ;" + "\\ help-coverage." + "[help.lint.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: { $examples { $example "USING: help.lint.coverage prettyprint ;" - "\"help.lint.coverage\" f ." + "\"english\" t ." "{ - { - T{ word-help-coverage - { word-name } - { 100%-coverage? t } - } - T{ word-help-coverage - { word-name } - { 100%-coverage? t } - } - T{ word-help-coverage - { word-name } - { 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: { $examples { $example "USING: help.lint.coverage prettyprint ;" - "\"help.lint.coverage\" ." + "\"english\" ." "{ T{ word-help-coverage - { word-name } - { 100%-coverage? t } + { word-name a10n } + { omitted-sections { $description $examples } } } T{ word-help-coverage - { word-name } - { 100%-coverage? t } + { word-name count-of-things } + { omitted-sections { $description $examples } } } T{ word-help-coverage - { word-name } - { 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 } } } }" } diff --git a/extra/help/lint/coverage/coverage-tests.factor b/extra/help/lint/coverage/coverage-tests.factor index b0faa881b9..0e09806c48 100644 --- a/extra/help/lint/coverage/coverage-tests.factor +++ b/extra/help/lint/coverage/coverage-tests.factor @@ -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 { t } [ \ empty empty-examples? ] unit-test @@ -33,4 +34,35 @@ PRIVATE> { { $values $description $examples } } [ \ keep word-defines-sections ] unit-test { { $values $contract $examples } } [ \ 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 [ ] map drop ] unit-test diff --git a/extra/help/lint/coverage/coverage.factor b/extra/help/lint/coverage/coverage.factor index 25a6383955..73e695d018 100644 --- a/extra/help/lint/coverage/coverage.factor +++ b/extra/help/lint/coverage/coverage.factor @@ -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 } ; > 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 -- coverage ) M: word - dup - [ missing-sections ] - [ empty-examples? ] bi + dup [ missing-sections ] [ empty-examples? ] bi 2dup 2array { { } f } = word-help-coverage boa ; inline M: string - loaded-vocab-names resolve-name-in ; inline + find-word ; inline : ( vocab-spec -- coverage ) [ auto-use? off vocab-words natural-sort [ ] map ] with-scope ; @@ -111,5 +126,23 @@ M: string auto-use? off group-articles vocab-articles set [ sorted-loaded-child-vocabs ] dip not [ filter-private ] when - [ ] map + [ ] 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 -- ) help-coverage. ; +: vocab-help-coverage. ( vocab-spec -- ) help-coverage. ; +: prefix-help-coverage. ( prefix-spec private? -- ) help-coverage. ;