UNIFY-3: Refined docstrings and added browseable API docs.

Author: fogus

README.md

@@ -41,10 +41,10 @@ org.clojure/core.unify {:mvn/version "0.7.2"}
       <version>0.7.2</version>
     </dependency>
 
+Usage
+=====
 
-
-Example Usage
-========================================
+Refer to docstrings in the `clojure.core.unify` namespace or browseable API documentation in docs/API.md.
 
 ```clojure
     (use 'clojure.core.unify)
@@ -55,17 +55,20 @@ Example Usage
     ;=> ((?a * 5 ** 2) + (4 * 5) + 3)
 ```
 
-Refer to docstrings in the `clojure.core.unify` namespace.
-
-
-
 Developer Information
 ========================================
 
 * [GitHub project](https://github.com/clojure/core.unify)
 * [Bug Tracker](https://clojure.atlassian.net/browse/UNIFY)
 * [Continuous Integration](https://github.com/clojure/core.unify/actions/workflows/test.yml)
 
+Running the tests at the command line against multiple CLJ versions:
+
+    ./run-tests.sh
+
+To generate the current API docs run the following:
+
+    clj -Tquickdoc quickdoc '{:outfile "docs/API.md", :github/repo "https://github.com/clojure/core.unify", :git/branch "master", :toc false}'
 
 Change Log
 ====================

docs/API.md

@@ -0,0 +1,174 @@
+
+-----
+# <a name="clojure.core.unify">clojure.core.unify</a>
+
+
+A unification library for Clojure.
+
+
+
+
+## <a name="clojure.core.unify/extract-lvars">`extract-lvars`</a><a name="clojure.core.unify/extract-lvars"></a>
+``` clojure
+
+(extract-lvars form)
+(extract-lvars lv-fn form)
+```
+
+Takes a datastructure form and returns a distinct set of the logical
+  variables found within. By default, the lvar? predicate is used to detect nested
+  lvars, but the function also accepts a custom predciate lv-fn to use instead.
+<p><sub><a href="https://github.com/clojure/core.unify/blob/master/src/main/clojure/clojure/core/unify.cljc#L25-L35">Source</a></sub></p>
+
+## <a name="clojure.core.unify/flatten-bindings">`flatten-bindings`</a><a name="clojure.core.unify/flatten-bindings"></a>
+``` clojure
+
+(flatten-bindings binds)
+(flatten-bindings variable? binds)
+```
+
+Flattens recursive bindings in binds to the same ground, if possible.
+  If a variable cannot be resolved then it is left in place.
+<p><sub><a href="https://github.com/clojure/core.unify/blob/master/src/main/clojure/clojure/core/unify.cljc#L136-L147">Source</a></sub></p>
+
+## <a name="clojure.core.unify/ignore-variable?">`ignore-variable?`</a><a name="clojure.core.unify/ignore-variable?"></a>
+``` clojure
+
+(ignore-variable? sym)
+```
+<p><sub><a href="https://github.com/clojure/core.unify/blob/master/src/main/clojure/clojure/core/unify.cljc#L16-L16">Source</a></sub></p>
+
+## <a name="clojure.core.unify/lvar?">`lvar?`</a><a name="clojure.core.unify/lvar?"></a>
+``` clojure
+
+(lvar? %1)
+```
+
+Returns true if a symbol represents a core.unify lvar.
+ By default, core.unify expects a symbol starting with ? or just _.
+<p><sub><a href="https://github.com/clojure/core.unify/blob/master/src/main/clojure/clojure/core/unify.cljc#L20-L23">Source</a></sub></p>
+
+## <a name="clojure.core.unify/make-occurs-subst-fn">`make-occurs-subst-fn`</a><a name="clojure.core.unify/make-occurs-subst-fn"></a>
+``` clojure
+
+(make-occurs-subst-fn variable-fn)
+```
+
+Given a function to recognize logic variables, returns a function that
+   will attempt to substitute unification bindings between two expressions.
+   This function uses an 'occurs check' to detect cycles.
+<p><sub><a href="https://github.com/clojure/core.unify/blob/master/src/main/clojure/clojure/core/unify.cljc#L180-L185">Source</a></sub></p>
+
+## <a name="clojure.core.unify/make-occurs-unifier-fn">`make-occurs-unifier-fn`</a><a name="clojure.core.unify/make-occurs-unifier-fn"></a>
+``` clojure
+
+(make-occurs-unifier-fn variable-fn)
+```
+
+Given a function to recognize logic variables, returns a function to
+   perform the unification of two expressions. This function uses an 'occurs check'
+   to detect cycles.
+<p><sub><a href="https://github.com/clojure/core.unify/blob/master/src/main/clojure/clojure/core/unify.cljc#L187-L192">Source</a></sub></p>
+
+## <a name="clojure.core.unify/make-occurs-unify-fn">`make-occurs-unify-fn`</a><a name="clojure.core.unify/make-occurs-unify-fn"></a>
+``` clojure
+
+(make-occurs-unify-fn variable-fn)
+```
+
+Given a function to recognize logic variables, returns a function to
+   return a bindings map for two expressions.  This function uses an 'occurs check'
+   to detect cycles.
+<p><sub><a href="https://github.com/clojure/core.unify/blob/master/src/main/clojure/clojure/core/unify.cljc#L171-L178">Source</a></sub></p>
+
+## <a name="clojure.core.unify/make-subst-fn">`make-subst-fn`</a><a name="clojure.core.unify/make-subst-fn"></a>
+``` clojure
+
+(make-subst-fn variable-fn)
+```
+
+Given a function to recognize unification variables, returns a function that
+  will attempt to substitute unification bindings between two expressions
+  without an 'occurs check'.
+<p><sub><a href="https://github.com/clojure/core.unify/blob/master/src/main/clojure/clojure/core/unify.cljc#L220-L225">Source</a></sub></p>
+
+## <a name="clojure.core.unify/make-unifier-fn">`make-unifier-fn`</a><a name="clojure.core.unify/make-unifier-fn"></a>
+``` clojure
+
+(make-unifier-fn variable-fn)
+```
+
+Given a function to recognize unification variables, returns a function to
+  perform the unification of two expressions without an 'occurs check'.
+<p><sub><a href="https://github.com/clojure/core.unify/blob/master/src/main/clojure/clojure/core/unify.cljc#L227-L235">Source</a></sub></p>
+
+## <a name="clojure.core.unify/make-unify-fn">`make-unify-fn`</a><a name="clojure.core.unify/make-unify-fn"></a>
+``` clojure
+
+(make-unify-fn variable-fn)
+```
+
+Given a function to recognize unification variables, returns a function to
+  return a bindings map for two expressions without an 'occurs check'.
+<p><sub><a href="https://github.com/clojure/core.unify/blob/master/src/main/clojure/clojure/core/unify.cljc#L212-L218">Source</a></sub></p>
+
+## <a name="clojure.core.unify/subst">`subst`</a><a name="clojure.core.unify/subst"></a>
+``` clojure
+
+(subst expression bindings)
+```
+
+Attempts to substitute the logic variables within an expression with their mapped values in bindings.
+<p><sub><a href="https://github.com/clojure/core.unify/blob/master/src/main/clojure/clojure/core/unify.cljc#L201-L203">Source</a></sub></p>
+
+## <a name="clojure.core.unify/unifier">`unifier`</a><a name="clojure.core.unify/unifier"></a>
+``` clojure
+
+(unifier expression1 expression2)
+```
+
+Attempts the entire unification process from garnering the bindings to substituting
+     the appropriate bindings, using an 'occurs check'.
+<p><sub><a href="https://github.com/clojure/core.unify/blob/master/src/main/clojure/clojure/core/unify.cljc#L205-L208">Source</a></sub></p>
+
+## <a name="clojure.core.unify/unifier-">`unifier-`</a><a name="clojure.core.unify/unifier-"></a>
+``` clojure
+
+(unifier- expression1 expression2)
+```
+
+Attempts the entire unification process from garnering the bindings to substituting
+the appropriate bindings. This function is not guranteed to terminate if cyclic logic variables
+are present.
+<p><sub><a href="https://github.com/clojure/core.unify/blob/master/src/main/clojure/clojure/core/unify.cljc#L244-L248">Source</a></sub></p>
+
+## <a name="clojure.core.unify/unify">`unify`</a><a name="clojure.core.unify/unify"></a>
+``` clojure
+
+(unify expression1 expression2)
+```
+
+Attempts to unify x and y with the given bindings (if any). May return a map of the
+unifiers (bindings) found. Will throw if an 'occurs check' determines that the expressions contain
+cyclic bindings or if the sub-expressions clash.
+<p><sub><a href="https://github.com/clojure/core.unify/blob/master/src/main/clojure/clojure/core/unify.cljc#L195-L199">Source</a></sub></p>
+
+## <a name="clojure.core.unify/unify-">`unify-`</a><a name="clojure.core.unify/unify-"></a>
+``` clojure
+
+(unify- expression1 expression2)
+```
+
+Attempt to unify x and y with the given bindings (if any). May return a map of the
+unifiers (bindings) found. Will throw if the sub-expressions clash. This function is not guranteed
+to terminate if cyclic logic variables are present.
+<p><sub><a href="https://github.com/clojure/core.unify/blob/master/src/main/clojure/clojure/core/unify.cljc#L237-L241">Source</a></sub></p>
+
+## <a name="clojure.core.unify/wildcard?">`wildcard?`</a><a name="clojure.core.unify/wildcard?"></a>
+``` clojure
+
+(wildcard? form)
+```
+
+Returns true if form starts with a core.unify wildcard. By default, core.unify expects the symbol &.
+<p><sub><a href="https://github.com/clojure/core.unify/blob/master/src/main/clojure/clojure/core/unify.cljc#L108-L112">Source</a></sub></p>

docs/Building.md

@@ -11,10 +11,4 @@ To test that the build succeeded try:
 
     mvn clojure:repl
 
-This will launch a Clojure REPL.  Try the following to exercise core.unify:
-
-```clojure
-:TODO
-```
-
-TODO
+This will launch a Clojure REPL.