clarify argument lists of helper functions

CHANGELOG.md

@@ -3,6 +3,7 @@
 * 2.1.next in progress
   * Fix #371 by treating the operand of `NOT` as a nested expression (so it is parenthesized unless it is a simple value).
   * Fix #370 by **always** parenthesizing the operand of `:nest`.
+  * Address #369 by adding a big clarifying docstring to the `honey.sql.helpers` namespace pointing out that all helper functions are variadic, they are all `[& args]`, some have `:arglists` metadata to provide a more specific usage hint but those _all omit the optional first argument (the DSL hash map)_.
   * Fix #354 by supporting `DROP COLUMN IF EXISTS` / `ADD COLUMN IF NOT EXISTS`.
   * Update `build-clj` to v0.5.5.
 

src/honey/sql/helpers.cljc

@@ -1,7 +1,49 @@
 ;; copyright (c) 2020-2021 sean corfield, all rights reserved
 
 (ns honey.sql.helpers
-  "Helper functions for the built-in clauses in honey.sql."
+  "Helper functions for the built-in clauses in honey.sql.
+
+  All helper functions are inherently variadic. Typical
+  usage is threaded, like this:
+
+```
+  (-> (select :a :b :c)
+      (from :table)
+      (where [:= :id 42])
+      (sql/format))
+```
+
+  Therefore all helpers can take an existing DSL expression
+  as their first argument or, if the first argument is not
+  a hash map, an empty DSL is assumed -- an empty hash map.
+  The above is therefore equivalent to:
+
+```
+  (-> {}
+      (select :a :b :c)
+      (from :table)
+      (where [:= :id 42])
+      (sql/format))
+```
+
+  Some of the helper functions here have `:arglists` metadata
+  in an attempt to provide better hints for auto-complete in
+  editors but those `:arglists` _always omit the DSL argument_
+  to avoid duplicating the various argument lists. When you
+  see an auto-complete suggestion like:
+
+    bulk-collect-into [varname] [varname n]
+
+  bear in mind that a DSL hash map can always be threaded in
+  so the following (pseudo) arities are also available:
+
+    bulk-collect-into [dsl varname] [dsl varname n]
+
+  The actual arguments are:
+
+    bulk-collect-info [& args]
+
+  (as they are for all helper functions)."
   (:refer-clojure :exclude [filter for group-by into partition-by set update])
   (:require [clojure.core :as c]
             [honey.sql]))