extra/descriptive/descriptive-docs.factor

   1 USING: help.syntax help.markup words ;
   2 IN: descriptive
   3
   4 HELP: DESCRIPTIVE:
   5 { $syntax "DESCRIPTIVE: word ( inputs -- outputs ) definition ;" }
   6 { $description "Defines a word such that, if an error is thrown from within it, that error is wrapped in a " { $link descriptive-error } " with the arguments to that word." } ;
   7
   8 HELP: DESCRIPTIVE::
   9 { $syntax "DESCRIPTIVE:: word ( inputs -- outputs ) definition ;" }
  10 { $description "Defines a word which uses locals such that, if an error is thrown from within it, that error is wrapped in a " { $link descriptive-error } " with the arguments to that word." } ;
  11
  12 HELP: descriptive-error
  13 { $error-description "The class of errors wrapping another error (in the underlying slot) which were thrown in a word (in the word slot) with a given set of arguments (in the args slot)." } ;
  14
  15 HELP: make-descriptive
  16 { $values { "word" word } }
  17 { $description "Makes the word wrap errors in " { $link descriptive-error } " instances." } ;
  18
  19 ARTICLE: "descriptive" "Descriptive errors"
  20 "This vocabulary defines automatic descriptive errors. Using it, you can define a word which acts as normal, except when it throws an error, the error is wrapped in an instance of a class:"
  21 { $subsections descriptive-error }
  22 "The wrapper contains the word itself, the input parameters, as well as the original error."
  23 $nl
  24 "To annotate an existing word with descriptive error checking:"
  25 { $subsections make-descriptive }
  26 "To define words which throw descriptive errors, use the following words:"
  27 { $subsections
  28     POSTPONE: DESCRIPTIVE:
  29     POSTPONE: DESCRIPTIVE::
  30 } ;
  31
  32 ABOUT: "descriptive"