v0.1 help.lint.pedantic

basis/help/lint/checks/tags.txt

@@ -0,0 +1 @@
+tools

basis/help/lint/pedantic/authors.txt

@@ -0,0 +1 @@
+Cat Stevens

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

@@ -0,0 +1,74 @@
+USING: help help.lint.pedantic help.markup help.syntax kernel
+strings words vocabs ;
+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 "
+{ $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:"
+{ $subsections
+    word-pedant
+    vocab-pedant
+    prefix-pedant
+} ;
+
+{ word-pedant vocab-pedant prefix-pedant } related-words
+
+HELP: ordinary-word-missing-section
+{ $values { "missing-section" string } { "word-name" string } }
+{ $description "Throws an " { $link ordinary-word-missing-section } " error." }
+{ $error-description "Thrown when an ordinary word's documentation is missing one of the sections " { $links $values $description $example } "." } ;
+
+HELP: prefix-pedant
+{ $values { "prefix" string } { "private?" boolean } }
+{ $description "Runs the help coverage checker on every child vocabulary of the given " { $snippet "prefix" } ", including the base vocabulary. If " { $snippet "private?" } " is " { $snippet "f" } ", the prefix's child " { $snippet ".private" } " vocabularies are not checked. If " { $snippet "private?" } " is " { $snippet "t" } ", " { $emphasis "all" } " child vocabularies are checked." }
+{ $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"
+}
+{ $examples
+  { $example
+      "USING: help.lint.pedantic ;"
+      "\"help.lint.pedantic\" f prefix-pedant"
+      ""
+  }
+} ;
+
+HELP: word-pedant
+{ $values { "word" { $or string word } } }
+{ $description "Runs the help coverage checker on the word described by " { $snippet "word-desc" } "." }
+{ $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"
+}
+{ $examples
+    { $example
+        "USING: help.lint.pedantic ;"
+        "\\ word-pedant word-pedant"
+        ""
+    }
+} ;
+
+HELP: vocab-pedant
+{ $values { "vocab-spec" { $or vocab string } } }
+{ $description "Runs the help coverage checker on the vocabulary in the given " { $snippet "vocab-spec" } "." }
+{ $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"
+}
+{ $examples
+    { $example
+      "USING: help.lint.pedantic ;"
+      "\"help.lint.pedantic\" vocab-pedant"
+      ""
+    }
+} ;

basis/help/lint/pedantic/pedantic.factor

@@ -0,0 +1,63 @@
+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 ;

basis/help/lint/pedantic/summary.txt

@@ -0,0 +1 @@
+Pedantic help coverage checker

basis/help/lint/pedantic/tags.txt

@@ -0,0 +1 @@
+tools