<commit_before>USING: accessors arrays combinators definitions generalizations
help help.markup help.topics kernel sequences sorting vocabs
words ;
IN: annotations

<PRIVATE
: comment-word ( base -- word ) "!" prepend "annotations" lookup ; 
: comment-usage-word ( base -- word ) "s" append "annotations" lookup ; 
: comment-usage.-word ( base -- word ) "s." append "annotations" lookup ; 
PRIVATE>

: $annotation ( element -- )
    first
    [ "!" " your comment here" surround 1array $syntax ]
    [ [ "Treats the rest of the line after the exclamation point as a code annotation that can be looked up with the " \ $link ] dip comment-usage.-word 2array " word." 3array $description ]
    [ ": foo ( x y z -- w )\n    !" " --w-ó()ò-w-- kilroy was here\n    + * ;" surround 1array $unchecked-example ]
    tri ;

: $annotation-usage. ( element -- )
    first
    [ "Displays a list of words, help articles, and vocabularies that contain " \ $link ] dip comment-word 2array " annotations." 3array $description ;

: $annotation-usage ( element -- )
    first
    { "usages" sequence } $values
    [ "Returns a list of words, help articles, and vocabularies that contain " \ $link ] dip [ comment-word 2array " annotations. For a more user-friendly display, use the " \ $link ] [ comment-usage.-word 2array " word." 6 narray ] bi 1array $description ;

"Code annotations"
{
    "The " { $vocab-link "annotations" } " vocabulary provides syntax for comment-like annotations that can be looked up with Factor's " { $link usage } " mechanism."
}
annotation-tags natural-sort
[
    [ \ $subsection swap comment-word 2array ] map append
    "To look up annotations:" suffix
] [
    [ \ $subsection swap comment-usage.-word 2array ] map append
] bi
<article> "annotations" add-article

"annotations" vocab "annotations" >>help drop

annotation-tags [
    {
        [ [ \ $annotation swap 2array 1array ] [ comment-word set-word-help ] bi ]
        [ [ \ $annotation-usage swap 2array 1array ] [ comment-usage-word set-word-help ] bi ]
        [ [ \ $annotation-usage. swap 2array 1array ] [ comment-usage.-word set-word-help ] bi ]
        [ [ comment-word ] [ comment-usage-word ] [ comment-usage.-word ] tri 3array related-words ]
    } cleave
] each<commit_msg>Tweak annotations docs so that help-lint passes<commit_after>USING: accessors arrays combinators definitions generalizations
help help.markup help.topics kernel sequences sorting vocabs
words combinators.smart ;
IN: annotations

<PRIVATE
: comment-word ( base -- word ) "!" prepend "annotations" lookup ; 
: comment-usage-word ( base -- word ) "s" append "annotations" lookup ; 
: comment-usage.-word ( base -- word ) "s." append "annotations" lookup ; 
PRIVATE>

: $annotation ( element -- )
    first
    [ "!" " your comment here" surround 1array $syntax ]
    [ [ "Treats the rest of the line after the exclamation point as a code annotation that can be looked up with the " \ $link ] dip comment-usage.-word 2array " word." 3array $description ]
    [ ": foo ( x y z -- w )\n    !" " --w-ó()ò-w-- kilroy was here\n    + * ;" surround 1array $code ]
    tri ;

: <$annotation> ( word -- element )
    \ $annotation swap 2array 1array ;

: $annotation-usage. ( element -- )
    first
    [ "Displays a list of words, help articles, and vocabularies that contain " \ $link ] dip comment-word 2array " annotations." 3array $description ;

: <$annotation-usage.> ( word -- element )
    \ $annotation-usage. swap 2array 1array ;

: $annotation-usage ( element -- )
    first [
        [ "Returns a list of words, help articles, and vocabularies that contain " ] dip
        [
            comment-word <$link>
            " annotations. For a more user-friendly display, use the "
        ] [
            comment-usage.-word <$link>
            " word."
        ] bi
    ] output>array $description ;

: <$annotation-usage> ( word -- element )
    [ { $values { "usages" sequence } } ] dip
    \ $annotation-usage swap 2array
    2array ;

"Code annotations"
{
    "The " { $vocab-link "annotations" } " vocabulary provides syntax for comment-like annotations that can be looked up with Factor's " { $link usage } " mechanism."
}
annotation-tags natural-sort
[
    [ \ $subsection swap comment-word 2array ] map append
    "To look up annotations:" suffix
] [
    [ \ $subsection swap comment-usage.-word 2array ] map append
] bi
<article> "annotations" add-article

"annotations" vocab "annotations" >>help drop

annotation-tags [
    {
        [ [ <$annotation> ] [ comment-word set-word-help ] bi ]
        [ [ <$annotation-usage> ] [ comment-usage-word set-word-help ] bi ]
        [ [ <$annotation-usage.> ] [ comment-usage.-word set-word-help ] bi ]
        [ [ comment-word ] [ comment-usage-word ] [ comment-usage.-word ] tri 3array related-words ]
    } cleave
] each
{'fraction_non_alphanumeric': 0.12668184640861105, 'fraction_numerical': 0.007037880356033948, 'mean_word_length': 2.8594249201277955, 'pattern_counts': {'":': 2, '<': 15, '<?xml version=': 0, '>': 20, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '5616615', 'n_tokens_mistral': 1475, 'n_tokens_neox': 1405, 'n_words': 469}