Documentation updates

CHANGELOG.md

@@ -1,6 +1,7 @@
 # Changes
 
 * 2.0.next in progress
+  * The documentation continues to be expanded and clarified in respond to feedback!
   * Tentative fix for #315 by expanding `:in` handling to deal with `nil` values.
 
 * 2.0.0-beta1 (for testing; 2021-04-09)

README.md

@@ -66,6 +66,8 @@ to a JDBC library, such as [`next.jdbc`](https://github.com/seancorfield/next-jd
 (jdbc/execute! conn (sql/format sqlmap))
 ```
 
+> Note: you'll need to add your preferred JDBC library as a dependency in your project -- HoneySQL deliberately does not make that choice for you.
+
 If you want to format the query as a string with no parameters (e.g. to use the SQL statement in a SQL console), pass `:inline true` as an option to `sql/format`:
 
 ```clojure
@@ -73,9 +75,7 @@ If you want to format the query as a string with no parameters (e.g. to use the
 => ["SELECT a, b, c FROM foo WHERE f.a = 'baz'"]
 ```
 
-> Note: you'll need to add your preferred JDBC library as a dependency in your project -- HoneySQL deliberately does not make that choice for you.
+Namespace-qualified keywords (and symbols) are generally treated as table-qualified columns: `:foo/bar` becomes `foo.bar`, except in contexts where that would be illegal (such as the list of columns in an `INSERT` statement). This approach is likely to be more compatible with code that uses libraries like [`next.jdbc`](https://github.com/seancorfield/next-jdbc) and [`seql`](https://github.com/exoscale/seql), as well as being more convenient in a world of namespace-qualified keywords, following the example of `clojure.spec` etc.
-
-Namespace-qualified keywords are generally treated as table-qualified columns: `:foo/bar` becomes `foo.bar`, except in contexts where that would be illegal (such as the list of columns in an `INSERT` statement). This approach is likely to be more compatible with code that uses libraries like [`next.jdbc`](https://github.com/seancorfield/next-jdbc) and [`seql`](https://github.com/exoscale/seql), as well as being more convenient in a world of namespace-qualified keywords, following the example of `clojure.spec` etc.
 
 ```clojure
 (def q-sqlmap {:select [:foo/a :foo/b :foo/c]
@@ -91,6 +91,11 @@ Namespace-qualified keywords are generally treated as table-qualified columns: `
 => ["SELECT foo.a, foo.b, foo.c FROM foo WHERE foo.a = ?" "baz"]
 ```
 
+Documentation for the entire data DSL can be found in the
+[Clause Reference](doc/clause-reference.md), the
+[Operator Reference](doc/operator-reference.md)], and the
+[Special Syntax referenc](doc/special-syntax.md).
+
 ### Vanilla SQL clause helpers
 
 For every single SQL clause supported by HoneySQL (as keywords or symbols
@@ -130,6 +135,8 @@ If you want to replace a clause, you can `dissoc` the existing clause first, sin
 => ["SELECT * FROM foo WHERE (f.a = ?) AND (b > ?)" "baz" 10]
 ```
 
+> Note: the helpers always produce keywords so you can rely on `dissoc` with the desired keyword to remove. If you are building the data DSL "manually" and using symbols instead of keywords, you'll need to `dissoc` the symbol form instead.
+
 `where` will combine multiple clauses together using SQL's `AND`:
 
 ```clojure
@@ -160,6 +167,9 @@ functions interchangably. For any example using the helpers, you could evaluate
 it (without the call to `sql/format`) to see what the equivalent data structure
 would be.
 
+Documentation for all the helpers can be found in the
+[`honey.sql.helpers` API reference](https://cljdoc.org/d/com.github.seancorfield/honeysql/CURRENT/api/honey.sql.helpers).
+
 ### Inserts
 
 Inserts are supported in two patterns.

doc/clause-reference.md

@@ -2,7 +2,8 @@
 
 This section lists all the SQL clauses that HoneySQL
 supports out of the box, in the order that they are
-processed for formatting.
+processed for formatting (except for some natural
+grouping of related clauses).
 
 Clauses can be specified as keywords or symbols. Use
 `-` in the clause name where the formatted SQL would have

doc/general-reference.md

@@ -57,7 +57,7 @@ when quoting is in effect:
 ```
 
 Finally, there are some contexts where only a SQL entity is accepted, rather than an
-arbitrary SQL expression, so a string will be treated as a SQL entity and in such cases
+arbitrary SQL expression, so a string will also be treated as a SQL entity and in such cases
 the entity name will always be quoted, dashes (`-`) will not be converted to
 underscores (`_`), and a slash (`/`) is not treated as separating a
 qualifier from the name, regardless of the `:dialect` or `:quoted` settings:
@@ -98,8 +98,12 @@ these tuples:
 ;;=> ["(?, ?, ?)" 13 42 "foo"]
 ```
 
+There is also a `composite` helper function.
+
 ## Other Sections Will Be Added!
 
+As questions arise about the use of HoneySQL 2.x, I will add new sections here.
+
 ## Other Reference Documentation
 
 The full list of supported SQL clauses is documented in the

doc/getting-started.md

@@ -169,9 +169,9 @@ call as the `:params` key of the options hash map.
 ## Functional Helpers
 
 In addition to the hash map (and sequences) approach of building
-SQL queries with raw Clojure data structures, a namespace full
+SQL queries with raw Clojure data structures, a
-of helper functions is also available. These functions are
+[namespace full of helper functions](https://cljdoc.org/d/com.github.seancorfield/honeysql/CURRENT/api/honey.sql.helpers)
-generally variadic and threadable:
+is also available. These functions are generally variadic and threadable:
 
 ```clojure
 (ns my.example
@@ -189,7 +189,7 @@ generally variadic and threadable:
 There is a helper function for every single clause that HoneySQL
 supports out of the box. In addition, there are helpers for
 `composite`, `lateral`, `over`, and `upsert` that make it easier to construct those
-parts of the SQL DSL (examples of `composite` appear in the [README](README.md),
+parts of the SQL DSL (examples of `composite` appear in the [README](/README.md),
 examples of `over` appear in the [Clause Reference](clause-reference.md))
 
 In addition to being variadic -- which often lets you omit one
@@ -231,7 +231,8 @@ you need to consider this when referring symbols in from the
 ## DDL Statements
 
 HoneySQL 1.x did not support any DDL statements. It was fairly
-common for people to use the [nilenso/honeysql-postgres library](https://github.com/nilenso/honeysql-postgres)
+common for people to use the
+[nilenso/honeysql-postgres library](https://github.com/nilenso/honeysql-postgres)
 to get DDL support, even if they didn't need the PostgreSQL-specific
 extensions. That library does not work with HoneySQL 2.x but all
 of the functionality from it (up to 0.3.104) has been incorporated
@@ -239,6 +240,9 @@ into HoneySQL now and is described in the [PostgreSQL](postgresql.md)
 section (because that covers all of the things that the nilenso
 library supported and much of it was PostgreSQL-specific!).
 
+See also the [DDL Clauses section](clause-reference.md#ddl-clauses) of
+the Clause Reference for documentation about supported DDL.
+
 ## Dialects
 
 By default, HoneySQL operates in ANSI SQL mode but it supports
@@ -308,6 +312,11 @@ was wrapped in `[:inline `..`]`:
 * keywords and symbols become SQL keywords (uppercase, with `-` replaced by a space),
 * everything else is just turned into a string (by calling `str`) and added to the SQL string.
 
+`format` accepts options as either a single hash map argument or
+as named arguments (alternating keys and values). If you are using
+Clojure 1.11 (or later) you can mix'n'match, providing some options
+as named arguments followed by other options in a hash map.
+
 ## Reference Documentation
 
 The full list of supported SQL clauses is documented in the

src/honey/sql.cljc

@@ -1206,7 +1206,12 @@
   any parameter values that were encountered in the DSL structure.
 
   This is the primary API for HoneySQL and handles dialects, quoting,
-  and named parameters."
+  and named parameters.
+
+  `format` accepts options as either a single hash map argument or
+  as named arguments (alternating keys and values). If you are using
+  Clojure 1.11 (or later) you can mix'n'match, providing some options
+  as named arguments followed by other options in a hash map."
   ([data] (format data {}))
   ([data opts]
    (let [dialect? (contains? opts :dialect)