extra/annotations/annotations-docs.factor

   1 USING: accessors arrays combinators combinators.smart help
   2 help.markup help.topics kernel sequences sorting tools.crossref
   3 vocabs words ;
   4 IN: annotations
   5
   6 <PRIVATE
   7 : comment-word ( base -- word ) "!" prepend "annotations" lookup-word ;
   8 : comment-usage-word ( base -- word ) "s" append "annotations" lookup-word ;
   9 : comment-usage.-word ( base -- word ) "s." append "annotations" lookup-word ;
  10 PRIVATE>
  11
  12 : $annotation ( element -- )
  13     first
  14     [ "!" " your comment here" surround 1array $syntax ]
  15     [ [ "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 ]
  16     [ ": foo ( x y z -- w )\n    !" " --w-ó()ò-w-- kilroy was here\n    + * ;" surround 1array $code ]
  17     tri ;
  18
  19 : <$annotation> ( word -- element )
  20     \ $annotation swap 2array 1array ;
  21
  22 : $annotation-usage. ( element -- )
  23     first
  24     [ "Displays a list of words, help articles, and vocabularies that contain " \ $link ] dip comment-word 2array " annotations." 3array $description ;
  25
  26 : <$annotation-usage.> ( word -- element )
  27     \ $annotation-usage. swap 2array 1array ;
  28
  29 : $annotation-usage ( element -- )
  30     first [
  31         [ "Returns a list of words, help articles, and vocabularies that contain " ] dip
  32         [
  33             comment-word <$link>
  34             " annotations. For a more user-friendly display, use the "
  35         ] [
  36             comment-usage.-word <$link>
  37             " word."
  38         ] bi
  39     ] output>array $description ;
  40
  41 : <$annotation-usage> ( word -- element )
  42     [ { $values { "usages" sequence } } ] dip
  43     \ $annotation-usage swap 2array
  44     2array ;
  45
  46 "Code annotations"
  47 {
  48     "The " { $vocab-link "annotations" } " vocabulary provides syntax for comment-like annotations that can be looked up with Factor's " { $link usage } " mechanism."
  49 }
  50 annotation-tags natural-sort
  51 [
  52     [ \ $subsection swap comment-word 2array ] map append
  53     "To look up annotations:" suffix
  54 ] [
  55     [ \ $subsection swap comment-usage.-word 2array ] map append
  56 ] bi
  57 <article> "annotations" add-article
  58
  59 "annotations" lookup-vocab "annotations" >>help drop
  60
  61 annotation-tags [
  62     {
  63         [ [ <$annotation> ] [ comment-word set-word-help ] bi ]
  64         [ [ <$annotation-usage> ] [ comment-usage-word set-word-help ] bi ]
  65         [ [ <$annotation-usage.> ] [ comment-usage.-word set-word-help ] bi ]
  66         [ [ comment-word ] [ comment-usage-word ] [ comment-usage.-word ] tri 3array related-words ]
  67     } cleave
  68 ] each