Additional documentation fixes and updates (#925)

Slowly chipping away at #666

Author: chrisrink10

CHANGELOG.md

@@ -22,9 +22,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
  * Fix a bug where reader column offset numbering began at 1, rather than 0 (#905)
 
 ### Other
- * Add REPL documentation module (#205)
+ * Add REPL documentation module (#205, #925)
  * Add documentation module for Basilisp interfaces (#920)
  * Add GitHub source links to generated API documentation (#921)
+ * Update Concepts documentation module with See Also links for most sections (#925)
  * Update Sphinx documentation theme (#909)
  * Update documentation to directly reference Python documentation and fix many other minor issues and misspellings (#907, #919)
 

docs/concepts.rst

@@ -5,54 +5,23 @@ Concepts
 
 .. lpy:currentns:: basilisp.core
 
-.. _seqs:
+.. _data_structures:
 
-Seqs
-----
+Data Structures
+---------------
 
 TBD
 
-.. _macros:
-
-Macros
-------
-
-Like many Lisps, Basilisp supports extending its syntax using macros.
-Macros are created using the :lpy:fn:`defmacro` macro in :lpy:ns:`basilisp.core`.
-Syntax for the macro usage generally matches that of the sibling :lpy:fn:`defn` macro, should be a relatively easy transition.
-
-Once a macro is defined, it is immediately available to the compiler.
-You may define a macro and then use it in the next form!
-
-The primary difference between a macro and a standard function is that macros are evaluated *at compile* time and they receive unevaluated expressions, whereas functions are evaluated *at runtime* and arguments will be fully evaluated before being passed to the function.
-Macros should return the unevaluated replacement code that should be compiled.
-Code returned by macros *must be legal code* -- symbols must be resolvable, functions must have the correct number of arguments, maps must have keys and corresponding values, etc.
-
-Macros created with ``defmacro`` automatically have access to two additional parameters (which *should not* be listed in the macro argument list): ``&env`` and ``&form``.
-``&form`` contains the original unevaluated form (including the invocation of the macro itself).
-``&env`` contains a mapping of all symbols available to the compiler at the time of macro invocation -- the values are maps representing the binding AST node.
-
-.. note::
-
-   Being able to extend the syntax of your language using macros is a powerful feature.
-   However, with great power comes great responsibility.
-   Introducing new and unusual syntax to a language can make it harder to onboard new developers and can make code harder to reason about.
-   Before reaching for macros, ask yourself if the problem can be solved using standard functions first.
+.. _seqs:
 
-.. warning::
+Seqs
+----
 
-   Macro writers should take care not to emit any references to :ref:`private_vars` in their macros, as these will not resolve for users outside of the namespace they are defined in, causing compile-time errors.
+TBD
 
 .. seealso::
 
-   :ref:`syntax_quoting`, :lpy:form:`quote`, :lpy:fn:`gensym`, :lpy:fn:`macroexpand`, :lpy:fn:`macroexpand-1`, :lpy:fn:`unquote`, :lpy:fn:`unquote-splicing`
-
-.. _binding_conveyance:
-
-Binding Conveyance
-------------------
-
-TBD
+   :lpy:fn:`lazy-seq`, :lpy:fn:`seq`, :lpy:fn:`first`, :lpy:fn:`rest`, :lpy:fn:`next`, :lpy:fn:`second`, :lpy:fn:`seq?`, :lpy:fn:`nfirst`, :lpy:fn:`fnext`, :lpy:fn:`nnext`, :lpy:fn:`empty?`, :lpy:fn:`seq?`, :py:class:`basilisp.lang.interfaces.ISeq`
 
 .. _destructuring:
 
@@ -74,6 +43,10 @@ Destructuring is supported everywhere names are bound: :lpy:form:`fn` argument v
 
    Names without a corresponding element in the data structure (typically due to absence) will bind to ``nil``.
 
+.. seealso::
+
+   :lpy:fn:`destructure`
+
 .. _sequential_destructuring:
 
 Sequential Destructuring
@@ -209,58 +182,200 @@ Both associative and sequential destructuring binding forms may be nested within
      [a b c e f])
    ;;=> [1 :b :c 4 5]
 
+.. _macros:
+
+Macros
+------
+
+Like many Lisps, Basilisp supports extending its syntax using macros.
+Macros are created using the :lpy:fn:`defmacro` macro in :lpy:ns:`basilisp.core`.
+Syntax for the macro usage generally matches that of the sibling :lpy:fn:`defn` macro, should be a relatively easy transition.
+
+Once a macro is defined, it is immediately available to the compiler.
+You may define a macro and then use it in the next form!
+
+The primary difference between a macro and a standard function is that macros are evaluated *at compile* time and they receive unevaluated expressions, whereas functions are evaluated *at runtime* and arguments will be fully evaluated before being passed to the function.
+Macros should return the unevaluated replacement code that should be compiled.
+Code returned by macros *must be legal code* -- symbols must be resolvable, functions must have the correct number of arguments, maps must have keys and corresponding values, etc.
+
+Macros created with ``defmacro`` automatically have access to two additional parameters (which *should not* be listed in the macro argument list): ``&env`` and ``&form``.
+``&form`` contains the original unevaluated form (including the invocation of the macro itself).
+``&env`` contains a mapping of all symbols available to the compiler at the time of macro invocation -- the values are maps representing the binding AST node.
+
+.. note::
+
+   Being able to extend the syntax of your language using macros is a powerful feature.
+   However, with great power comes great responsibility.
+   Introducing new and unusual syntax to a language can make it harder to onboard new developers and can make code harder to reason about.
+   Before reaching for macros, ask yourself if the problem can be solved using standard functions first.
+
+.. warning::
+
+   Macro writers should take care not to emit any references to :ref:`private_vars` in their macros, as these will not resolve for users outside of the namespace they are defined in, causing compile-time errors.
+
+.. seealso::
+
+   :ref:`syntax_quoting`, :lpy:form:`quote`, :lpy:fn:`gensym`, :lpy:fn:`macroexpand`, :lpy:fn:`macroexpand-1`, :lpy:fn:`unquote`, :lpy:fn:`unquote-splicing`
+
+.. _metadata:
+
+Metadata
+--------
+
+TBD
+
+.. seealso::
+
+   :ref:`Reading metadata on literals <reader_metadata>`, :lpy:fn:`meta`, :lpy:fn:`with-meta`, :lpy:fn:`vary-meta`, :lpy:fn:`alter-meta!`, :lpy:fn:`reset-meta!`
+
+.. _delays:
+
+Delays
+------
+
+Delays are containers for deferring expensive computations until such time as the result is needed.
+Create a new delay with the :lpy:fn:`delay` macro.
+Results will not be computed until you attempt to :lpy:fn:`deref` or :lpy:fn:`force` evaluation.
+Once a delay has been evaluated, it caches its results and returns the cached results on subsequent accesses.
+
+.. code-block::
+
+   basilisp.user=> (def d (delay (println "evaluating") (+ 1 2 3)))
+   #'basilisp.user/d
+
+   basilisp.user=> d
+   <basilisp.lang.delay.Delay object at 0x1077803a0>
+
+   basilisp.user=> (force d)
+   evaluating
+   6
+
+   basilisp.user=> (force d)
+   6
+
+.. seealso::
+
+   :lpy:fn:`delay`, :lpy:fn:`delay?`, :lpy:fn:`force`, :lpy:fn:`realized?`, :lpy:fn:`deref`
+
+.. _promises:
+
+Promises
+--------
+
+Promises are containers for receiving a deferred result, typically from another thread.
+The value of a promise can be written exactly once using :lpy:fn:`deliver`.
+Threads may await the results of the promise using a blocking :lpy:fn:`deref` call.
+
+.. seealso::
+
+   :lpy:fn:`promise`, :lpy:fn:`deliver`, :lpy:fn:`realized?`, :lpy:fn:`deref`
+
+.. _atoms:
+
+Atoms
+-----
+
+TBD
+
+.. seealso::
+
+   :lpy:fn:`atom`, :lpy:fn:`compare-and-set!`, :lpy:fn:`reset!`, :lpy:fn:`reset-vals!`, :lpy:fn:`swap!`, :lpy:fn:`swap-vals!`, :lpy:fn:`deref`, :ref:`references_and_refs`
+
 .. _references_and_refs:
 
 References and Refs
 -------------------
 
 TBD
 
+.. seealso::
+
+   :lpy:fn:`alter-meta!`, :lpy:fn:`reset-meta!`, :lpy:fn:`add-watch`, :lpy:fn:`remove-watch`, :lpy:fn:`get-validator`, :lpy:fn:`set-validator!`
+
+.. _transients:
+
+Transients
+----------
+
+TBD
+
+.. seealso::
+
+   :lpy:fn:`transient`, :lpy:fn:`persistent!`, :lpy:fn:`assoc!`, :lpy:fn:`conj!`, :lpy:fn:`disj!`, :lpy:fn:`dissoc!`, :lpy:fn:`pop!`
+
 .. _volatiles:
 
 Volatiles
 ---------
 
 TBD
 
+.. seealso::
+
+   :lpy:fn:`volatile!`, :lpy:fn:`volatile?`, :lpy:fn:`vreset!`, :lpy:fn:`vswap!`
+
 .. _transducers:
 
 Transducers
 -----------
 
 TBD
 
+.. seealso::
+
+   :lpy:fn:`eduction`, :lpy:fn:`completing`, :lpy:fn:`halt-when`, :lpy:fn:`sequence`, :lpy:fn:`transduce`, :lpy:fn:`into`, :lpy:fn:`cat`
+
 .. _hierarchies:
 
 Hierarchies
 -----------
 
 TBD
 
+.. seealso::
+
+   :lpy:fn:`make-hierarchy`, :lpy:fn:`ancestors`, :lpy:fn:`descendents`, :lpy:fn:`parents`, :lpy:fn:`isa?`, :lpy:fn:`derive`, :lpy:fn:`underive`
+
 .. _multimethods:
 
 Multimethods
 ------------
 
 TBD
 
+.. seealso::
+
+   :lpy:fn:`defmulti`, :lpy:fn:`defmethod`, :lpy:fn:`methods`, :lpy:fn:`get-method`, :lpy:fn:`prefer-method`, :lpy:fn:`prefers`, :lpy:fn:`remove-method`, :lpy:fn:`remove-all-methods`
+
 .. _protocols:
 
 Protocols
 ---------
 
 TBD
 
+.. seealso::
+
+   :lpy:fn:`defprotocol`, :lpy:fn:`protocol?`, :lpy:fn:`extend`, :lpy:fn:`extend-protocol`, :lpy:fn:`extend-type`, :lpy:fn:`extenders`, :lpy:fn:`extends?`, :lpy:fn:`satisfies?`
+
 .. _data_types:
 
 Data Types
 ----------
 
 TBD
 
+.. seealso::
+
+   :lpy:fn:`deftype`
+
 .. _records:
 
 Records
 -------
 
-TBD
+TBD
+
+.. seealso::
+
+   :ref:`records` , :lpy:fn:`defrecord` , :lpy:fn:`record?`

docs/index.rst

@@ -25,6 +25,7 @@ Contents
    features
    gettingstarted
    differencesfromclojure
+   concepts
    reference
    releasenotes
    contributing

docs/reader.rst

@@ -11,9 +11,6 @@ The Basilisp reader performs a job which is a combination of the traditional lex
 The reader takes a file or string and produces a stream of Basilisp data structures.
 Typically the reader streams its results to the compiler, but end-users may also take advantage of the reader directly from within Basilisp.
 
-.. contents:: Reader Literals
-   :depth: 2
-
 .. _numeric_literals:
 
 Numeric Literals
@@ -356,7 +353,7 @@ All of the text to the end of the line are ignored.
 
 For a convenience in writing shell scripts with Basilisp, the standard \*NIX `shebang <https://en.wikipedia.org/wiki/Shebang_(Unix)>`_ (``#!``) is also treated as a single-line comment.
 
-.. _metadata:
+.. _reader_metadata:
 
 Metadata
 --------
@@ -380,6 +377,10 @@ Metadata applied to a form must be one of: :ref:`maps`, :ref:`symbols`, :ref:`ke
 * Keyword metadata will be normalized to a Map with the keyword as the key with the value of ``true``.
 * Map metadata will not be modified when it is read.
 
+.. seealso::
+
+   :ref:`metadata`
+
 .. _reader_macros:
 
 Reader Macros
@@ -462,6 +463,10 @@ In nearly all cases, this will be the return value from a macro function, which
 
    Using any of these special syntax quoting characters outside of a syntax quote context will result in a compiler error.
 
+.. seealso::
+
+   :ref:`macros`
+
 .. _reader_conditions:
 
 Reader Conditionals

docs/reference.rst

@@ -13,6 +13,5 @@ Reference
    specialforms
    pyinterop
    runtime
-   concepts
    testing
    compiler

docs/repl.rst

@@ -65,6 +65,27 @@ This namespace includes some utilities for introspecting the runtime environment
 
    :lpy:fn:`require`, :lpy:fn:`refer`, :lpy:fn:`use`
 
+.. _taps:
+
+Taps
+^^^^
+
+Basilisp supports the concept of "taps" as a convenient, non-blocking method of monitoring the operation of some function at runtime.
+Taps are implemented as a simple in-process publish/subscribe mechanism.
+Users can add tap functions using :lpy:fn:`add-tap` which subscribe to a topic (typically a keyword) or which use the default ``:basilisp.core.tap/default``.
+Functions can then emit tap events at runtime into the queue using :lpy:fn:`tap>` with a topic and a background thread will call any tap functions which have subscribed to the topic.
+Taps can be removed using :lpy:fn:`remove-tap`.
+
+.. warning::
+
+   The background thread uses a :external:py:class:`queue.Queue` to store and process its results.
+   The queue size is limited to 1024 items by default to avoid excessive memory consumption.
+   Users can configure the queue size by setting the environment variable ``BASILISP_TAP_QUEUE_SIZE`` to an integer value.
+
+.. seealso::
+
+   :lpy:fn:`tap>`, :lpy:fn:`add-tap`, :lpy:fn:`remove-tap`
+
 .. _repl_creature_comforts:
 
 Creature Comforts

docs/runtime.rst

@@ -152,7 +152,20 @@ Note that this functionality already exists as :lpy:fn:`with-out-str`, but it se
 
 .. seealso::
 
-   :lpy:fn:`binding`, :lpy:fn:`bound-fn`, :lpy:fn:`bound-fn*`, :lpy:fn:`get-thread-bindings`, :lpy:fn:`pop-thread-bindings`, :lpy:fn:`push-thread-bindings`, :lpy:fn:`with-bindings`, :lpy:fn:`with-bindings*`
+   :lpy:fn:`binding`
+
+
+.. _binding_conveyance:
+
+Binding Conveyance
+##################
+
+Basilisp supports the concept of "binding conveyance" which allows copying the active set of dynamic Var bindings in the current thread when submitting work to another thread.
+Both :lpy:fn:`future` and :lpy:fn:`pmap` support this feature natively.
+
+.. seealso::
+
+    :lpy:fn:`bound-fn`, :lpy:fn:`bound-fn*`, :lpy:fn:`get-thread-bindings`, :lpy:fn:`pop-thread-bindings`, :lpy:fn:`push-thread-bindings`, :lpy:fn:`with-bindings`, :lpy:fn:`with-bindings*`
 
 .. _private_vars: