Add generator article

diff --git a/extra/generators/generators-docs.factor b/extra/generators/generators-docs.factor
index f4676faad218556c15ae3bd15b55eea49c247489..3c518d4d414da225faed76205353c9e82100135c 100644 (file)
--- a/extra/generators/generators-docs.factor
+++ b/extra/generators/generators-docs.factor
@@ -135,7 +135,28 @@ HELP: yield-from
 { $description "Delegate computation to the specified generator until it is exhausted, before resuming computation in the current generator." } ;
 
 ARTICLE: "generators" "Generators"
-{ $vocab-link "generators" }
+"Generators in Factor are lazily executed blocks of code, which emit values on request. They are designed to work very similarly to generators found in languages like Python or JavaScript. "
+" Their implementation in Factor is a simple wrapper around " { $vocab-link "coroutines" } "."
+$nl
+"Generator words are created using " { $link \ GEN: } " or " { $link \ GEN:: } ". When a generator word is called, its required inputs are consumed from the stack, and a "
+{ $link generator } " object is left as output. Accordingly, the right hand side of generator word's stack effect must always be a single value. For example:"
+$nl
+{ $code "GEN: repeat-forever ( val -- gen ) [ dup yield t ] loop ;" "GEN:: foo ( a b c -- gen ) b yield c yield a yield ;" }
+"Inside generator words, " { $link yield } " and its variants can be used. These words halt execution and pass a value to the caller. When a generator object is depleted (i.e., the word is fully finished executing), a "
+{ $link stop-generator } " error is thrown. This error can also be thrown manually inside a generator word to end execution early."
+$nl
+"When a generator object is depleted, its runtime is discarded and therefore any values left on its internal stack are ignored. "
+"Generator objects can also be created directly from quotations using " { $link <generator> } "."
+$nl
+"Once generator objects have been created, there are multiple words to control them."
+$nl
+"Progressing computation:"
+{ $subsections next ?next skip take take-all }
+"Provide a value to generator, and progress the computation:"
+{ $subsections next* ?next* skip* }
+"Check if a generator is already exhausted:"
+{ $subsections exhausted? }
+"All generator words are found in the " { $vocab-link "generators" } "vocabulary."
 ;
 
 ABOUT: "generators"