v0.2 help.lint.pedantic: move to extra
Cat Stevens
John Benediktsson
parent
28336323b4
commit
de3d01daef
|
|
@ -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 ;
|
||||
|
|
@ -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
|
||||
|
|
@ -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 ;
|
||||
Loading…
Reference in New Issue