factor/library/tools/annotations.facts

IN: words
USING: help ;

HELP: annotate "( word quot -- )"
{ $values { "word" "a word" } { "quot" "a quotation with stack effect " { $snippet "( word def -- def )" } } }
{ $description "Changes a word definition to the result of applying a quotation to the old definition." }
{ $notes "This is the common word to implement " { $link watch } ", " { $link break } ", " { $link break-on } " and " { $link profile } "." } ;

HELP: watch "( word -- )"
{ $values { "word" "a word" } }
{ $description "Changes a word definition so that a message together with the stack contents is output before and after the word runs." } ;

HELP: break "( word -- )"
{ $values { "word" "a word" } }
{ $description "Changes a word definition so that it runs in the single stepper. See " { $link "walker" } "." } ;

HELP: break-on "( word quot -- )"
{ $values { "word" "a word" } { "quot" "a quotation with stack effect " { $snippet "( -- ? )" } } }
{ $description "Changes a word definition so that the quotation runs first, and if it outputs a true value, the word runs in the single stepper. See " { $link "walker" } "." } ;

HELP: profile "( word -- )"
{ $values { "word" "a word" } }
{ $description "Changes a word definition so that the total runtime is added to a variable keyed by the word in the global namespace." }
{ $examples
    { $example 
        ": foo 1000000 [ drop ] each ;\n\\ foo profile\n\\ foo get ." "931"
    }
} ;