Some more documentation!

doc/differences-from-1-x.md

@@ -83,7 +83,7 @@ The `:quoting <dialect>` option has superseded by the new dialect machinery and
 Identifiers are automatically quoted if you specify a `:dialect` option to `format`, unless you also specify `:quoted false`.
 
 The following options are no longer supported:
-* `:allow-dashed-names?` -- if you provide dashed-names in v2, they will be left as-is if quoting is enabled, else they will be converted to snake_case (so you will either get `"dashed-names"` with quoting or `dashed_names` without); v1 treated names specified as keywords and names specified as strings differently.
+* `:allow-dashed-names?` -- if you provide dashed-names in v2, they will be left as-is if quoting is enabled, else they will be converted to snake_case (so you will either get `"dashed-names"` with quoting or `dashed_names` without).
 * `:allow-namespaced-names?` -- this supported `foo/bar` column names in SQL which I'd like to discourage.
 * `:namespace-as-table?` -- this is the default in v2: `:foo/bar` will be treated as `foo.bar` which is more in keeping with `next.jdbc`.
 * `:parameterizer` -- this would add a lot of complexity to the formatting engine and I do not know how widely it was used (especially in its arbitrarily extensible form).
@@ -102,7 +102,7 @@ The following new syntax has been added:
 * `:case` -- this is now explicit syntax,
 * `:cast` -- `[:cast expr :type]` => `CAST( expr AS type )`,
 * `:composite` -- explicit syntax to produce a comma-separated list of expressions, wrapped in parentheses,
-* `:default` -- for `DEFAULT` values (in inserts),
+* `:default` -- for `DEFAULT` values (in inserts) and for declaring column defaults in table definitions,
 * `:inline` -- used as a function to replace the `sql/inline` / `#sql/inline` machinery,
 * `:interval` -- used as a function to support `INTERVAL <n> <units>`, e.g., `[:interval 30 :days]`.
 * `:lift` -- used as a function to prevent interpretation of a Clojure data structure as DSL syntax (e.g., when passing a vector or hash map as a parameter value),
@@ -113,6 +113,11 @@ The following new syntax has been added:
 
 > Note 1: in 1.x, inlining a string `"foo"` produced `foo` but in 2.x it produces `'foo'`, i.e., string literals become SQL strings without needing internal quotes (1.x required `"'foo'"`).
 
+Several additional pieces of syntax have also been added to support column
+definitions in `CREATE TABLE` clauses, now that v2 supports DDL statement
+construction: `:constraint`, `:foreign-key`, `:index`, `:primary-key`,
+`:references`, `:unique`, and -- as noted above -- `:default`.
+
 You can now `SELECT` a function call more easily, using `[[...]]`. This was previously an error -- missing an alias -- but it was a commonly requested change, to avoid using `(sql/call ...)`:
 
 ```clojure

doc/getting-started.md

@@ -52,12 +52,14 @@ or symbols, are treated as positional parameters and replaced
 by `?` in the SQL string and lifted out into the vector that
 is returned from `format`.
 
-Nearly all clauses expect a vector as their value, containing
+Most clauses expect a vector as their value, containing
 either a list of SQL entities or the representation of a SQL
-expression.
+expression. Some clauses accept a single SQL entity. A few
+accept a most specialized form (such as `:set` accepting a
+hash map of SQL entities and SQL expressions).
 
 A SQL entity can be a simple keyword (or symbol) or a pair
-that represents a SQL entity and its alias:
+that represents a SQL entity and its alias (where aliases are allowed):
 
 ```clojure
 (sql/format {:select [:t.id [:name :item]], :from [[:table :t]], :where [:= :id 1]})
@@ -76,6 +78,8 @@ avoid evaluation:
 
 ```clojure
 (sql/format '{select [t.id [name item]], from [[table t]], where [= id 1]})
+;; or you can use (..) instead of [..] when quoted:
+(sql/format '{select (t.id (name item)), from ((table t)), where (= id 1)})
 ;; also produces:
 ;;=> ["SELECT t.id, name AS item FROM table AS t WHERE id = ?" 1]
 ```
@@ -110,6 +114,12 @@ generally variadic and threadable:
 ;;=> ["SELECT t.id, name AS item FROM table AS t WHERE id = ?" 1]
 ```
 
+There is a helper function for every single clause that HoneySQL
+supports out of the box. In addition, there are helpers for
+`composite` and `over` that make it easier to construct those
+parts of the SQL DSL (examples of the former appear in the [README.md](README),
+examples of the latter appear in the [docs/clause-reference.md](Clause Reference))
+
 In addition to being variadic -- which often lets you omit one
 level of `[`..`]` -- the helper functions merge clauses, which
 can make it easier to build queries programmatically:
@@ -123,3 +133,36 @@ can make it easier to build queries programmatically:
 ;; produces:
 ;;=> ["SELECT t.id, name AS item FROM table AS t WHERE id = ?" 1]
 ```
+
+If you want to replace a clause with a subsequent helper call,
+you need to explicitly remove the prior value:
+
+```clojure
+(-> (select :t/id)
+    (from [:table :t])
+    (where [:= :id 1])
+    (dissoc :select)
+    (select [:name :item])
+    (sql/format))
+;; produces:
+;;=> ["SELECT name AS item FROM table AS t WHERE id = ?" 1]
+```
+
+Helpers always use keywords when constructing clauses so you
+can rely on using keywords in `dissoc`.
+
+The following helpers shadow functions in `clojure.core` so
+you need to consider this when referring symbols in from the
+`honey.sql.helpers` namespace: `for`, `group-by`, `partition-by`,
+`set`, and `update`.
+
+## Reference Documentation
+
+The full list of supported SQL clauses is documented in the
+[docs/clause-reference.md](Clause Reference). The full list
+of "special syntax" functions is documented in the
+[docs/special-syntax.md](Special Syntax) section. The best
+documentation for the helper functions is the
+[honey.sql.helpers](https://cljdoc.org/d/seancorfield/honeysql/CURRENT/api/honey.sql.helpers).
+If you're migrating to HoneySQL 2.0, this [overview of differences
+between 1.0 and 2.0](docs/differences-from-1-x.md) should help.