From de3d01daef8071358313a8ddfd22f0f00e07e568 Mon Sep 17 00:00:00 2001 From: Cat Stevens Date: Fri, 2 Feb 2018 14:11:47 -0500 Subject: [PATCH] v0.2 help.lint.pedantic: move to extra --- basis/help/lint/pedantic/pedantic.factor | 63 -------------- .../help/lint/pedantic/authors.txt | 0 .../help/lint/pedantic/pedantic-docs.factor | 39 +++++---- extra/help/lint/pedantic/pedantic.factor | 82 +++++++++++++++++++ .../help/lint/pedantic/summary.txt | 0 {basis => extra}/help/lint/pedantic/tags.txt | 0 6 files changed, 106 insertions(+), 78 deletions(-) delete mode 100644 basis/help/lint/pedantic/pedantic.factor rename {basis => extra}/help/lint/pedantic/authors.txt (100%) rename {basis => extra}/help/lint/pedantic/pedantic-docs.factor (54%) create mode 100644 extra/help/lint/pedantic/pedantic.factor rename {basis => extra}/help/lint/pedantic/summary.txt (100%) rename {basis => extra}/help/lint/pedantic/tags.txt (100%) diff --git a/basis/help/lint/pedantic/pedantic.factor b/basis/help/lint/pedantic/pedantic.factor deleted file mode 100644 index 211ae96707..0000000000 --- a/basis/help/lint/pedantic/pedantic.factor +++ /dev/null @@ -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 ; - -> _ 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/authors.txt b/extra/help/lint/pedantic/authors.txt similarity index 100% rename from basis/help/lint/pedantic/authors.txt rename to extra/help/lint/pedantic/authors.txt diff --git a/basis/help/lint/pedantic/pedantic-docs.factor b/extra/help/lint/pedantic/pedantic-docs.factor similarity index 54% rename from basis/help/lint/pedantic/pedantic-docs.factor rename to extra/help/lint/pedantic/pedantic-docs.factor index 36cab929d8..5db259717b 100644 --- a/basis/help/lint/pedantic/pedantic-docs.factor +++ b/extra/help/lint/pedantic/pedantic-docs.factor @@ -1,17 +1,20 @@ -USING: help help.lint.pedantic help.markup help.syntax kernel -strings words vocabs ; +USING: help help.lint.pedantic help.lint.pedantic.private help.markup help.syntax kernel +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 " -{ $link $example } ", " -{ $link $description } ", and " -{ $link $values } -" sections (see " { $link "element-types" } ")." +"pedant, " { $emphasis "n." } " one who pays more attention to formal rules and book learning than they merit." $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 -{ $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: missing-sections +{ $values { "missing-sections" sequence } { "word-name" word } } +{ $description "Throws an " { $link missing-sections } " error." } +{ $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 diff --git a/extra/help/lint/pedantic/pedantic.factor b/extra/help/lint/pedantic/pedantic.factor new file mode 100644 index 0000000000..14056e5c4b --- /dev/null +++ b/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 } ; + +> "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 ; diff --git a/basis/help/lint/pedantic/summary.txt b/extra/help/lint/pedantic/summary.txt similarity index 100% rename from basis/help/lint/pedantic/summary.txt rename to extra/help/lint/pedantic/summary.txt diff --git a/basis/help/lint/pedantic/tags.txt b/extra/help/lint/pedantic/tags.txt similarity index 100% rename from basis/help/lint/pedantic/tags.txt rename to extra/help/lint/pedantic/tags.txt