v0.2 help.lint.pedantic: move to extra

basis/help/lint/pedantic/pedantic.factor

@@ -1,63 +0,0 @@
-USING: accessors classes combinators.short-circuit eval
-formatting fry help help.lint help.lint.checks help.markup
-kernel namespaces parser prettyprint sequences sorting splitting
-strings summary vocabs words ;
-IN: help.lint.pedantic
-
-ERROR: ordinary-word-missing-section missing-section word-name ;
-ERROR: empty-examples word-name ;
-
-M: empty-examples summary
-    word-name>> "Word '%s' has defined empty $examples section" sprintf ;
-
-M: ordinary-word-missing-section summary
-    [ word-name>> ] [ missing-section>> ] bi
-    "Word '%s' should define %s help section" sprintf ;
-
-<PRIVATE
-
-: elements-by ( element elt-type -- seq )
-    swap elements ;
-
-: checked-ordinary-word? ( word -- ? )
-    {
-        [ word-help \ $predicate elements-by empty? ]
-        [ class? not ]
-    } 1&& ;
-
-: check-ordinary-word-sections ( word -- )
-    [ word-help ] keep '[
-        [ elements-by ] keep swap
-        [ name>> _ ordinary-word-missing-section ]
-        [ 2drop ] if-empty
-    ]
-    { [ \ $values ] [ \ $description ] [ \ $examples ] }
-    [ prepose ] with map
-    [ call( x -- ) ] with each ;
-
-: missing-examples? ( word -- ? )
-    word-help \ $examples elements-by empty? ;
-
-: check-ordinary-word-examples ( word -- )
-    [ missing-examples? ] keep '[ _ empty-examples ] when ;
-PRIVATE>
-
-GENERIC: word-pedant ( word -- )
-M: word word-pedant
-    dup checked-ordinary-word? [
-        [ check-ordinary-word-sections ] [ check-ordinary-word-examples ] bi
-    ] [ drop ] if ; inline
-
-M: string word-pedant
-    "\\ " prepend eval( -- word ) word-pedant ; inline
-
-: vocab-pedant ( vocab-spec -- )
-    [ auto-use? off vocab-words natural-sort [ word-pedant ] each ] with-scope ;
-
-: prefix-pedant ( prefix private? -- )
-    [
-        auto-use? off group-articles vocab-articles set
-        [ loaded-child-vocab-names natural-sort ] dip not
-        [ [ ".private" ?tail nip not ] filter ] when
-        [ vocab-pedant ] each
-    ] with-scope ;

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

@@ -1,17 +1,20 @@
-USING: help help.lint.pedantic help.markup help.syntax kernel
+USING: help help.lint.pedantic help.lint.pedantic.private help.markup help.syntax kernel
-strings words vocabs ;
+sequences strings vocabs words ;
 IN: help.lint.pedantic
 
 ABOUT: "help.lint.pedantic"
 
 ARTICLE: "help.lint.pedantic" "Pedantic help coverage"
-"The " { $vocab-link "help.lint.pedantic" } " vocabulary implements a very picky documentation completeness checker. Intended to be used alongside " { $vocab-link "help.lint" } " in writing documenation, the pedantic linter requires all ordinary words to have documentation defining the "
+"pedant, " { $emphasis "n." } " one who pays more attention to formal rules and book learning than they merit."
-{ $link $example } ", "
-{ $link $description } ", and "
-{ $link $values }
-" sections (see " { $link "element-types" } ")."
 $nl
-"The following words are provided to aid in writing more complete documentation:"
+"The " { $vocab-link "help.lint.pedantic" } " vocabulary implements a very picky documentation completeness checker -- your very own documentation pedant."
+$nl
+"The pedantic linter requires most words to have documentation defining the "
+{ $links $values $description $error-description $class-description $examples } " sections (see " { $links "element-types" } ")."
+$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:"
 { $subsections
     word-pedant
     vocab-pedant
@@ -19,11 +22,17 @@ $nl
 } ;
 
 { word-pedant vocab-pedant prefix-pedant } related-words
+{ missing-sections empty-examples } related-words
 
-HELP: ordinary-word-missing-section
+HELP: missing-sections
-{ $values { "missing-section" string } { "word-name" string } }
+{ $values { "missing-sections" sequence } { "word-name" word } }
-{ $description "Throws an " { $link ordinary-word-missing-section } " error." }
+{ $description "Throws an " { $link missing-sections } " error." }
-{ $error-description "Thrown when an ordinary word's documentation is missing one of the sections " { $links $values $description $example } "." } ;
+{ $error-description "Thrown when a word's documentation is missing one or more sections required for it by " { $link should-define } "." } ;
+
+HELP: empty-examples
+{ $values { "word-name" word } }
+{ $description "Throws an " { $link empty-examples } " error." }
+{ $error-description "Thrown when a word's " { $link $examples } " section is missing or empty." } ;
 
 HELP: prefix-pedant
 { $values { "prefix" string } { "private?" boolean } }
@@ -31,7 +40,7 @@ HELP: prefix-pedant
 { $errors
     { $link empty-examples } " if a word has an empty " { $snippet "$examples" } " section
 "
-    { $link ordinary-word-missing-section } " if a word is missing a section entirely"
+    { $link missing-sections } " if a word is missing a section entirely"
 }
 { $examples
   { $example
@@ -47,7 +56,7 @@ HELP: word-pedant
 { $errors
     { $link empty-examples } " if a word has an empty " { $snippet "$examples" } " section
 "
-    { $link ordinary-word-missing-section } " if a word is missing a section entirely"
+    { $link missing-sections } " if a word is missing a section entirely"
 }
 { $examples
     { $example
@@ -63,7 +72,7 @@ HELP: vocab-pedant
 { $errors
     { $link empty-examples } " if a word has an empty " { $snippet "$examples" } " section
 "
-    { $link ordinary-word-missing-section } " if a word is missing a section entirely"
+    { $link missing-sections } " if a word is missing a section entirely"
 }
 { $examples
     { $example

extra/help/lint/pedantic/pedantic.factor

@@ -0,0 +1,82 @@
+USING: accessors arrays classes combinators
+combinators.short-circuit continuations english eval formatting
+fry help help.lint help.lint.checks help.markup kernel
+namespaces parser prettyprint sequences sets sorting splitting
+strings summary vocabs words ;
+FROM: namespaces => set ;
+IN: help.lint.pedantic
+
+ERROR: missing-sections
+    { word-name word initial: POSTPONE: f }
+    { missing-sections sequence initial: { } } ;
+ERROR: empty-examples { word-name initial: POSTPONE: f } ;
+
+<PRIVATE
+DEFER: ?pluralize
+
+M: empty-examples summary
+    word-name>> "Word '%s' has defined empty $examples section" sprintf ;
+
+M: missing-sections summary
+    [ word-name>> ] [
+        missing-sections>> dup [
+            length "section" ?pluralize
+        ] dip
+        [ name>> ] map ", " join
+    ] bi
+    "Word '%s' should define help %s: %s" sprintf ;
+
+: sorted-loaded-child-vocabs ( prefix -- assoc )
+    loaded-child-vocab-names natural-sort ; inline
+
+: filter-private ( seq -- no-private )
+    [ ".private" ?tail nip not ] filter ; inline
+
+: ?pluralize ( n singular -- singular/plural )
+    count-of-things " " split1 nip ;
+
+: should-define ( word -- spec )
+    {
+        { [ dup predicate? ] [ drop { } ] } ! predicate?s have generated docs
+        { [ dup error? ] [ drop { $values $description $error-description } ] }
+        { [ dup class? ] [ drop { $class-description } ] }
+        { [ dup word? ]  [ drop { $values $description $examples } ] }
+        [ drop no-cond ]
+    } cond ;
+
+: word-defines-sections ( word -- seq )
+    word-help [ first ] map ;
+
+: missing-examples? ( word -- ? )
+    word-help \ $examples swap elements empty? ;
+
+: check-examples ( word -- )
+    [ missing-examples? ] keep '[ _ empty-examples ] when ;
+
+: check-sections ( word -- )
+    [ ] [ should-define ] [ word-defines-sections ] tri
+    diff [ drop ] [ missing-sections ] if-empty ;
+PRIVATE>
+
+GENERIC: word-pedant ( word -- )
+M: word word-pedant
+    {
+        { [ dup predicate? ] [ drop ] }
+        { [ dup error? ] [ check-sections ] }
+        { [ dup word? ] [ [ check-sections ] [ check-examples ] bi ] }
+        [ drop no-cond ]
+    } cond ; inline
+
+M: string word-pedant
+    "\\ " prepend eval( -- word ) word-pedant ; inline
+
+: vocab-pedant ( vocab-spec -- )
+    [ auto-use? off vocab-words natural-sort [ word-pedant ] each ] with-scope ;
+
+: prefix-pedant ( prefix private? -- )
+    [
+        auto-use? off group-articles vocab-articles set
+        [ sorted-loaded-child-vocabs ] dip not
+        [ filter-private ] when
+        [ vocab-pedant ] each
+    ] with-scope ;