refactor help.lint.coverage with complete docs and tests

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
+USING: help help.lint.coverage help.lint.coverage.private
-sequences strings vocabs words ;
+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 ;"
+        "USING: help.lint.coverage ;"
-        "\\ <word-help-coverage> <word-help-coverage> print-coverage"
+        "\\ <word-help-coverage> <word-help-coverage> help-coverage."
-        "Word '<word-help-coverage>' has 100% 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
-        T{ word-help-coverage
+        { word-name a10n }
-            { word-name <prefix-help-coverage> }
+        { omitted-sections { $description $examples } }
-            { 100%-coverage? t }
+    }
-        }
+    T{ word-help-coverage
-        T{ word-help-coverage
+        { word-name count-of-things }
-            { word-name <vocab-help-coverage> }
+        { omitted-sections { $description $examples } }
-            { 100%-coverage? t }
+    }
-        }
+    T{ word-help-coverage
-        T{ word-help-coverage
+        { word-name pluralize }
-            { word-name <word-help-coverage> }
+        { omitted-sections { $description $examples } }
-            { 100%-coverage? t }
+    }
-        }
+    T{ word-help-coverage
-        T{ word-help-coverage
+        { word-name singularize }
-            { word-name print-coverage }
+        { omitted-sections { $description $examples } }
-            { 100%-coverage? t }
+    }
-        }
+    T{ word-help-coverage
-        T{ word-help-coverage
+        { word-name match-case }
-            { word-name word-help-coverage }
+        { omitted-sections { $description $examples } }
-            { 100%-coverage? t }
+    }
-        }
+    T{ word-help-coverage
-        T{ word-help-coverage
+        { word-name plural-to-singular }
-            { word-name word-help-coverage? }
+        { omitted-sections { $description $examples } }
-            { 100%-coverage? t }
+    }
-        }
+    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> }
+        { word-name a10n }
-        { 100%-coverage? t }
+        { omitted-sections { $description $examples } }
     }
     T{ word-help-coverage
-        { word-name <vocab-help-coverage> }
+        { word-name count-of-things }
-        { 100%-coverage? t }
+        { omitted-sections { $description $examples } }
     }
     T{ word-help-coverage
-        { word-name <word-help-coverage> }
+        { word-name pluralize }
-        { 100%-coverage? t }
+        { omitted-sections { $description $examples } }
     }
     T{ word-help-coverage
-        { word-name print-coverage }
+        { word-name singularize }
-        { 100%-coverage? t }
+        { omitted-sections { $description $examples } }
-    }
-    T{ word-help-coverage
-        { word-name word-help-coverage }
-        { 100%-coverage? t }
-    }
-    T{ word-help-coverage
-        { word-name word-help-coverage? }
-        { 100%-coverage? t }
     }
 }"
     }

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

@@ -1,5 +1,6 @@
-USING: help.lint.coverage help.lint.coverage.private help.markup
+USING: accessors fuel.help.private help.lint.coverage
-help.syntax kernel math.matrices sorting tools.test vocabs ;
+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

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
+fry fuel.help.private generic help help.lint help.lint.checks help.markup io
-kernel math namespaces parser prettyprint sequences sets sorting
+io.streams.string io.styles kernel math namespaces parser
-splitting strings summary vocabs words ;
+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
+: write-object-seq ( object-seq -- )
-    [ word-name>> [ vocabulary>> ] [ name>> ] bi "[%s] %s: " sprintf ] keep
-    dup 100%-coverage?>>
-    [ drop "full help coverage" append ]
     [
-        [ empty-examples?>> "defined empty { $examples }, " "" ? ]
+        dup array? [
-        [ omitted-sections>> dup [
+            dup ?first array?
-                length "section" ?pluralize
+            [ dup length '[
-            ] dip
+                    swap first2 write-object
-            [ name>> ] map ", " join
+                    _ 1 - abs = not [ " " write ] when
-        ] bi
+                ] each-index
-        "%sshould define help %s %s" sprintf append
+            ] [ first2 write-object ] if
-    ] if ; inline
+        ] [ 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
+    dup [ missing-sections ] [ empty-examples? ] bi
-    [ 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. ;