From f5744d4f213d3ff342cbb626df52cc65761a4abc Mon Sep 17 00:00:00 2001
From: Sean Corfield <sean@corfield.org>
Date: Thu, 23 Mar 2023 19:29:09 -0700
Subject: [PATCH] fix #480 by adding notes about DSL clause to/from helper
 mapping

---
 CHANGELOG.md            | 1 +
 README.md               | 4 ++++
 doc/clause-reference.md | 5 +++++
 doc/getting-started.md  | 4 ++++
 4 files changed, 14 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8b389f4..1a78b11 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,7 @@
 
 * 2.4.next in progress
   * Address [#481](https://github.com/seancorfield/honeysql/issues/481) by adding more examples around `:do-update-set`.
+  * Address [#480](https://github.com/seancorfield/honeysql/issues/480) by clarifying the general relationship between clauses and helpers.
 
 * 2.4.1006 -- 2023-03-17
   * Fix [#478](https://github.com/seancorfield/honeysql/issues/478) by handling `:do-update-set` correctly in the `upsert` helper and by handling parameters correctly in the `:do-update-set` formatter.
diff --git a/README.md b/README.md
index 54c37f9..1d2aa77 100644
--- a/README.md
+++ b/README.md
@@ -157,6 +157,10 @@ function in the `honey.sql.helpers` namespace:
 => {:select [:a :b :c] :from [:foo] :where [:= :foo.a "baz"]}
 ```
 
+In general, `(helper :foo expr)` will produce `{:helper [:foo expr]}`
+(with a few exceptions -- see the docstring of the helper function
+for details).
+
 Order doesn't matter (for independent clauses):
 
 ```clojure
diff --git a/doc/clause-reference.md b/doc/clause-reference.md
index aea4a18..d8e1b5b 100644
--- a/doc/clause-reference.md
+++ b/doc/clause-reference.md
@@ -22,6 +22,11 @@ The examples herein assume:
                                            where order-by over partition-by window]])
 ```
 
+Every DDL and SQL clause has a corresponding helper function
+in `honey.sql.helpers`. In general, `(helper :foo expr)` will
+produce `{:helper [:foo expr]}` (with a few exceptions -- see
+the docstring of the helper function for details).
+
 # DDL Clauses
 
 HoneySQL supports the following DDL clauses as a data DSL.
diff --git a/doc/getting-started.md b/doc/getting-started.md
index fb8c3c2..a76cada 100644
--- a/doc/getting-started.md
+++ b/doc/getting-started.md
@@ -277,6 +277,10 @@ supports out of the box. In addition, there are helpers for
 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 general, `(helper :foo expr)` will produce `{:helper [:foo expr]}`
+(with a few exceptions -- see the docstring of the helper function
+for details).
+
 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: