extra/annotations/annotations-docs.factor

   1 USING: accessors arrays combinators definitions generalizations
   2 help help.markup help.topics kernel sequences sorting vocabs
   3 words ;
   4 IN: annotations
   5
   6 <PRIVATE
   7 : comment-word ( base -- word ) "!" prepend "annotations" lookup ;
   8 : comment-usage-word ( base -- word ) "s" append "annotations" lookup ;
   9 : comment-usage.-word ( base -- word ) "s." append "annotations" lookup ;
  10 PRIVATE>
  11
  12 "Code annotations"
  13 {
  14     "The " { $vocab-link "annotations" } " vocabulary provides syntax for comment-like annotations that can be looked up with Factor's " { $link usage } " mechanism."
  15 }
  16 annotation-tags natural-sort
  17 [
  18     [ \ $subsection swap comment-word 2array ] map append
  19     "To look up annotations:" suffix
  20 ] [
  21     [ \ $subsection swap comment-usage.-word 2array ] map append
  22 ] bi
  23 <article> "annotations" add-article
  24
  25 "annotations" vocab "annotations" >>help drop
  26
  27 annotation-tags [
  28     {
  29         [ [ \ $syntax ] dip "!" " your comment here" surround 2array ]
  30         [ [ \ $description "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." 4array ]
  31         [ [ \ $unchecked-example ] dip ": foo ( x y z -- w )\n    !" " --w-ó()ò-w-- kilroy was here\n    + * ;" surround 2array 3array ]
  32         [ comment-word set-word-help ]
  33
  34         [ [ \ $description "Displays a list of words, help articles, and vocabularies that contain " \ $link ] dip comment-word 2array " annotations." 4array 1array ]
  35         [ comment-usage.-word set-word-help ]
  36
  37         [ [ { $values { "usages" sequence } } \ $description "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 2array ] bi ]
  38         [ comment-usage-word set-word-help ]
  39
  40         [ [ comment-word ] [ comment-usage-word ] [ comment-usage.-word ] tri 3array related-words ]
  41     } cleave
  42 ] each