... This Source Code Form is subject to the terms of the Mozilla Public License, v. 2.0.
... If a copy of the MPL was not distributed with this file, You can obtain one at https://mozilla.org/MPL/2.0/.

(.require
 [library
  [lux (.except)
   ["$" documentation]
   [data
    [text (.only \n)
     ["%" \\format (.only format)]]]]]
 [\\library
  ["[0]" /]])

(def .public documentation
  (.List $.Documentation)
  (list ($.module /._
                  "")

        ($.definition /.functor)
        ($.definition /.apply)
        ($.definition /.monad)

        ($.definition (/.Async it)
          "Represents values produced by asynchronous computations (unlike IO, which is synchronous).")

        ($.definition (/.Resolver it)
          (format "The function used to give a value to an async."
                  \n "Will signal 'true' if the async has been resolved for the 1st time, 'false' otherwise."))

        ($.definition /.resolved
          "Produces an async that has already been resolved to the given value."
          ($.example (resolved value)))

        ($.definition /.async
          "Creates a fresh async that has not been resolved yet."
          ($.example (async _)))

        ($.definition /.value
          "Polls an async for its value.")

        ($.definition /.upon!
          "Executes the given function as soon as the async has been resolved."
          ($.example (upon! function async)))

        ($.definition /.resolved?
          "Checks whether an async's value has already been resolved.")

        ($.definition /.and
          "Combines the results of both asyncs, in-order."
          ($.example (and left right)))

        ($.definition /.or
          (format "Yields the results of whichever async gets resolved first."
                  \n "You can tell which one was resolved first through pattern-matching.")
          ($.example (or left right)))

        ($.definition /.either
          (format "Yields the results of whichever async gets resolved first."
                  \n "You cannot tell which one was resolved first.")
          ($.example (either left right)))

        ($.definition /.schedule!
          (format "Runs an I/O computation on its own thread (after a specified delay)."
                  \n "Returns an async that will eventually host its result.")
          ($.example (schedule! milli_seconds computation)))

        ($.definition /.future
          (format "Runs an I/O computation on its own thread."
                  \n "Returns an async that will eventually host its result.")
          ($.example (future computation)))

        ($.definition /.after
          "Delivers a value after a certain period has passed."
          ($.example (after milli_seconds value)))

        ($.definition /.delay
          "An async that will be resolved after the specified amount of milli-seconds."
          ($.example (delay milli_seconds)))

        ($.definition /.within
          "Wait for an async to be resolved within the specified amount of milli-seconds."
          ($.example (within milli_seconds async)))
        ))