Add example docstring

src/boot/boot.janet

@@ -529,39 +529,58 @@
   (each-template x ds :each body))
 
 (defmacro loop
-  "A general purpose loop macro. This macro is similar to the Common Lisp
+  ``A general purpose loop macro. This macro is similar to the Common Lisp
   loop macro, although intentionally much smaller in scope.
   The head of the loop should be a tuple that contains a sequence of
   either bindings or conditionals. A binding is a sequence of three values
-  that define something to loop over. They are formatted like:\n\n
+  that define something to loop over. They are formatted like:
-  \tbinding :verb object/expression\n\n
+
-  Where binding is a binding as passed to def, :verb is one of a set of keywords,
+      binding :verb object/expression
-  and object is any expression. The available verbs are:\n\n
+
-  \t:iterate - repeatedly evaluate and bind to the expression while it is truthy.\n
+  Where `binding` is a binding as passed to def, `:verb` is one of a set of
-  \t:range - loop over a range. The object should be a two-element tuple with a start
+  keywords, and `object` is any expression. The available verbs are:
-  and end value, and an optional positive step. The range is half open, [start, end).\n
+
-  \t:range-to - same as :range, but the range is inclusive [start, end].\n
+  * :iterate -- repeatedly evaluate and bind to the expression while it is
-  \t:down - loop over a range, stepping downwards. The object should be a two-element tuple
+    truthy.
-  with a start and (exclusive) end value, and an optional (positive!) step size.\n
+
-  \t:down-to - same :as down, but the range is inclusive [start, end].\n
+  * :range -- loop over a range. The object should be a two-element tuple with
-  \t:keys - iterate over the keys in a data structure.\n
+    a start and end value, and an optional positive step. The range is half
-  \t:pairs - iterate over the key-value pairs as tuples in a data structure.\n
+    open, [start, end).
-  \t:in - iterate over the values in a data structure.\n
+
-  \t:generate - iterate over values yielded from a fiber. Can be paired with the generator
+  * :range-to -- same as :range, but the range is inclusive [start, end].
-  function for the producer/consumer pattern.\n\n
+
-  loop also accepts conditionals to refine the looping further. Conditionals are of
+  * :down -- loop over a range, stepping downwards. The object should be a
-  the form:\n\n
+    two-element tuple with a start and (exclusive) end value, and an optional
-  \t:modifier argument\n\n
+    (positive!) step size.
-  where :modifier is one of a set of keywords, and argument is keyword-dependent.
+
-  :modifier can be one of:\n\n
+  * :down-to -- same :as down, but the range is inclusive [start, end].
-  \t:while expression - breaks from the loop if expression is falsey.\n
+
-  \t:until expression - breaks from the loop if expression is truthy.\n
+  * :keys -- terate over the keys in a data structure.
-  \t:let bindings - defines bindings inside the loop as passed to the let macro.\n
+
-  \t:before form - evaluates a form for a side effect before the next inner loop.\n
+  * :pairs -- iterate over the key-value pairs as tuples in a data structure.
-  \t:after form - same as :before, but the side effect happens after the next inner loop.\n
+
-  \t:repeat n - repeats the next inner loop n times.\n
+  * :in -- iterate over the values in a data structure.
-  \t:when condition - only evaluates the loop body when condition is true.\n\n
+
-  The loop macro always evaluates to nil."
+  * :generate -- iterate over values yielded from a fiber. Can be paired with
+    the generator function for the producer/consumer pattern.
+
+  `loop` also accepts conditionals to refine the looping further. Conditionals are of
+  the form:
+
+      :modifier argument
+
+  where `:modifier` is one of a set of keywords, and `argument` is keyword-dependent.
+  `:modifier` can be one of:
+
+    * `:while expression` - breaks from the loop if `expression` is falsey.
+    * `:until expression` - breaks from the loop if `expression` is truthy.
+    * `:let bindings` - defines bindings inside the loop as passed to the `let` macro.
+    * `:before form` - evaluates a form for a side effect before the next inner loop.
+    * `:after form` - same as `:before`, but the side effect happens after the next inner loop.
+    * `:repeat n` - repeats the next inner loop `n` times.
+    * `:when condition` - only evaluates the loop body when condition is true.
+
+  The `loop` macro always evaluates to nil.``
   [head & body]
   (loop1 body head 0))