diff --git a/basis/help/lint/checks/tags.txt b/basis/help/lint/checks/tags.txt new file mode 100644 index 0000000000..ef1aab0d0e --- /dev/null +++ b/basis/help/lint/checks/tags.txt @@ -0,0 +1 @@ +tools diff --git a/basis/help/lint/pedantic/authors.txt b/basis/help/lint/pedantic/authors.txt new file mode 100644 index 0000000000..9d4a8e15ee --- /dev/null +++ b/basis/help/lint/pedantic/authors.txt @@ -0,0 +1 @@ +Cat Stevens diff --git a/basis/help/lint/pedantic/pedantic-docs.factor b/basis/help/lint/pedantic/pedantic-docs.factor new file mode 100644 index 0000000000..36cab929d8 --- /dev/null +++ b/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" + "" + } +} ; diff --git a/basis/help/lint/pedantic/pedantic.factor b/basis/help/lint/pedantic/pedantic.factor new file mode 100644 index 0000000000..211ae96707 --- /dev/null +++ b/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 ; + +> _ 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 ; diff --git a/basis/help/lint/pedantic/summary.txt b/basis/help/lint/pedantic/summary.txt new file mode 100644 index 0000000000..c42033cd5e --- /dev/null +++ b/basis/help/lint/pedantic/summary.txt @@ -0,0 +1 @@ +Pedantic help coverage checker diff --git a/basis/help/lint/pedantic/tags.txt b/basis/help/lint/pedantic/tags.txt new file mode 100644 index 0000000000..ef1aab0d0e --- /dev/null +++ b/basis/help/lint/pedantic/tags.txt @@ -0,0 +1 @@ +tools